Component contracts

Button

Example contract · demo „buttons“
src/components/ui/button.tsx
Responsibility

Actions use Button; navigation uses buttonVariants on a native anchor. Pass type="button" for non-submit actions.

Reuse
Not set separately – the demo is the contract
Entry point
src/components/ui/button.tsx
Constraints and rules
  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
Consumers in source

34 direct imports · Website reference

  • src/components/case/CaseBlock.astro
  • src/components/case/CaseHero.astro
  • src/components/ContactBlock.astro
  • src/components/CvPreview.astro
  • + 30 more

Path from a website route: src/pages/about/index.astro → src/components/ui/button.tsx

Variants
  • variant: primary | secondary | ghost | link
  • size: sm | md | icon
  • asChild: boolean (React composition only)
States
  • default
  • hover
  • focus-visible
  • disabled
  • aria-busy + disabled (composition)
API (read from source)
Button({className, variant, size, asChild = false, ...props}: React.ComponentProps<'button'> & VariantProps<typeof buttonVariants> & {asChild?: boolean})
Full documentation

Live · Rendered from the existing demoRendered from the catalog exampleA real block from a case, through CaseBlockCaseLab

Buttons

Usage and source contract

Actions use Button; navigation uses buttonVariants on a native anchor. Pass type="button" for non-submit actions.

Primary source: src/components/ui/button.tsx

Variants: variant: primary | secondary | ghost | link · size: sm | md | icon · asChild: boolean (React composition only)

States: default · hover · focus-visible · disabled · aria-busy + disabled (composition)

  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
<Button type="button" variant="secondary" size="sm">Save</Button>
<Button type="button" aria-busy="true" disabled>Saving…</Button>

Input

Usage and source contract

Use Input for native text/search fields. Always connect a visible label; errors use aria-invalid and aria-describedby.

Primary source: src/components/ui/input.tsx

Variants: size: sm | md · native input props except numeric size

States: empty · filled · focus-visible · disabled · readOnly · aria-invalid + aria-describedby

  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
<label for="search">Search work</label>
<Input id="search" type="search" size="md" />

Tags

neutral · mdbrand · mdok · mdwarn · mddanger · mdmeta · md
neutral · smbrand · smok · smwarn · smdanger · smmeta · sm
Usage and source contract

Badge communicates a short label, never release status without evidence. State text must remain readable without color.

Primary source: src/components/ui/badge.tsx

Variants: tone: neutral | brand | ok | warn | danger | meta · size: md | sm · dot: boolean

States: default · keyboard focus where interactive · light / dark · reduced motion

  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
<div class="flex flex-wrap gap-2">
    <Badge dot>neutral</Badge><Badge tone="brand" dot>brand</Badge><Badge tone="ok" dot>ok</Badge><Badge tone="warn" dot>warn</Badge><Badge tone="danger" dot>danger</Badge>
  </div>
  <div class="flex flex-wrap gap-2"><Badge size="sm" tone="meta">Chat</Badge><Badge size="sm" tone="brand">Human Gate</Badge><Badge size="sm" tone="ok">Autonom</Badge><Badge size="sm" tone="warn">Ausstehend</Badge></div>

Card

A calm surface

Cards hold one unit of content and lift off the page by one shadow step.

Flagship
Usage and source contract

Reuse this composition from its source and demo. Keep its existing semantic structure and locale/data contracts.

Primary source: src/components/ui/card.tsx

src/components/ui/badge.tsx

src/components/ui/separator.tsx

States: default · keyboard focus where interactive · light / dark · reduced motion

  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
<Card className="max-w-text">
    <CardHeader><CardTitle>{t(locale, 'ds.cardTitle')}</CardTitle><CardDescription>{t(locale, 'ds.cardBody')}</CardDescription></CardHeader>
    <Separator />
    <div class="flex gap-2"><Badge tone="brand" dot>{t(locale, 'flag.tag')}</Badge></div>
  </Card>

Table

FigureWhat
0 → 1One entry point for every zvoove product, from the first shell prototype to shipping with the zvoove One bundles.
4 → 14Grew the Container xChange design team as Design Co-Lead.
Seven figuresOutstanding customer receivables brought back, a joint initiative in finance.
Since 2017My own design systems, from car2go and SHARE NOW to Compass.
Usage and source contract

Reuse this composition from its source and demo. Keep its existing semantic structure and locale/data contracts.

Primary source: src/components/ui/table.tsx

States: default · keyboard focus where interactive · light / dark · reduced motion

  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
<div class="overflow-hidden rounded-card bg-panel shadow-lift">
    <Table>
      <TableHeader><TableRow><TableHead>{locale === 'de' ? 'Kennzahl' : 'Figure'}</TableHead><TableHead>{locale === 'de' ? 'Was' : 'What'}</TableHead></TableRow></TableHeader>
      <TableBody>
        {proof.map((n) => <TableRow><TableCell className="text-lg font-medium text-ink tabular-nums">{t(locale, `proof.${n}.v`)}</TableCell><TableCell>{t(locale, `proof.${n}.t`)}</TableCell></TableRow>)}
      </TableBody>
    </Table>
  </div>

Dialog, menu, tooltip

Usage and source contract

Use the existing Radix dialog/menu/tooltip wrappers. Dialogs require an accessible title and focus return; tooltips never carry essential content alone.

Primary source: src/components/ds/PrimitiveDemos.astro

src/components/islands/DsDialogDemo.tsx

src/components/islands/DsTooltipDemo.tsx

src/components/islands/PanelMenu.tsx

src/components/islands/PreRead.tsx

States: default · keyboard focus where interactive · light / dark · reduced motion

  • Use native semantics and visible keyboard focus.
  • Check 320px, long content and both themes.
<div class="flex flex-wrap items-center gap-3">
    <DsDialogDemo client:visible open={t(locale, 'ds.dialogOpen')} title={t(locale, 'ds.dialogTitle')} body={t(locale, 'ds.dialogBody')} close={t(locale, 'ds.close')} />
    <PanelMenu client:visible label={t(locale, 'ds.menuLabel')} items={[{label: t(locale, 'ds.menuAll'), href: '/work/'}, {label: t(locale, 'ds.menuCv'), href: t(locale, 'nav.cvHref')}]} />
    <DsTooltipDemo client:visible trigger={t(locale, 'ds.tooltipTrigger')} text={t(locale, 'ds.tooltip')} />
    <PreRead client:visible trigger={t(locale, 'preread.open')} title={t(locale, 'preread.title')} intro={t(locale, 'preread.intro')} items={[t(locale, 'preread.1'), t(locale, 'preread.2'), t(locale, 'preread.3')]} closeLabel={t(locale, 'ds.close')} />
  </div>
How designers use the kitQ3 2022 → T2 2023How designers use the kit. Q3 2022, 5 designers: 3 at one-offs, 2 at adapt and give back. T2 2023, 7 designers: all 7 at extend by the rules.
Extend by the rules
0%100%+100 pp
One-offs
60%0%−60 pp

1 · One-offsOne-offsEvery design a one-off, so-called snowflakes.2 · MixMixOne-offs and global components, adapted personally.3 · Adapt and give backAdapt and give backAdapt global components and give the change back to the system.4 · Extend by the rulesExtend by the rulesUse global components, extend them by set rules or request new variants.5 · Global components onlyGlobal components onlyWithout any adaptation.

One answer per designer.

  1. case → embed?theme=light|dark, {type:'lab:theme'}
  2. embed → case{type:'lab:height', height}
  3. originlocation.origin

Opened directly. Inside a case, CaseLab draws the window around this page, sends the theme as lab:theme and takes the height from lab:height.

Source: design-system/manifest.json, generated from catalog.json, registry/*.json and usage.json with npm run ds:manifest.