# Design system guidance for coding agents

The design system behind https://kayhan.me, written for an AI coding tool that is about to build UI for this site. Generated from the stylesheet on every build: token names, values, statuses and contrast ratios are read from source, not typed. Human-readable version: https://kayhan.me/design-system. Structured version: https://kayhan.me/design-system.json.

## Before you write anything

- One global stylesheet is loaded on every page. Write a scoped style block for your component; never edit the token files.
- `*` already sets the font (`var(--sans)`), the weight (`var(--fw-500)`) and the colour (`var(--text-primary)`). Inherit them.
- A global `:focus-visible` ring already exists. Leave it alone.
- Fluid tokens travel between 390px and 1920px. For `--space-*`, `--radius-*` and the type ramp, the number in the name is the size at 1920px.
- If a rule below is in your way, stop and say so. Do not work around it.

## Rules

Each rule has an id. Every one of them is checked against component source by the site build.

### Tokens

- **known-tokens**: Use only custom properties that exist in the stylesheet. Do not invent token names. Why: An unknown var() fails silently: the browser drops the declaration and the component quietly falls back to defaults.
- **no-reserve**: Do not use tokens whose status is reserve. Why: Reserve tokens are kept on purpose but have no job. Giving one a job is a design decision, not an implementation detail.

### Colour

- **semantic-colour**: Take every colour from the semantic layer (--surface-*, --text-*, --accent*, --brand-*, --border*). Never name a palette step such as --rose-700 or --gray-500. Why: The semantic layer is the only colour surface a module may consume, which is what lets a palette step change without hunting through modules. A grep gate in the repo enforces it.
- **no-literal-colour**: Do not write colour literals: no hex, rgb(), hsl() or named colours. transparent and currentColor are fine. Why: A literal is a colour the system does not know about, so it escapes the contrast table and every future palette change.
- **contrast**: Pair text and ground at 4.5:1 or better. The pairings in the contrast table are already checked; prefer them. Why: WCAG AA for body copy. The table is computed from resolved values on every build, so it cannot go stale.

### Type

- **type-ramp**: Set font sizes from the type ramp (--h1, --h2, --h3, --h4, --h5, --h6, --display-sm, --p-lg, --p, --p-sm). Never from --size-* or a literal, and never below --p-sm. Why: The ramp is fluid and monotonic: each step stays below the one above it at every width. --size-* is fixed and would not scale with the copy around it. --p-sm is 14px at its smallest, the floor for readable text.
- **one-family**: Leave font-family alone. At Haüss (--sans) is set on every element; --serif is for pull-quotes only. Why: One face carries the whole interface. The other three are licensed, loaded and deliberately idle or reserved for one job.
- **weights**: Set font weights from --fw-*, using the active steps only (400 to 800). Why: All four families are variable, so any number renders, which is exactly why the steps are named: a 650 is a weight nobody chose.

### Space and size

- **space-for-rhythm**: Use --space-* for padding, margin and gap. The number is the maximum, reached at 1920px. Why: --space-* is fluid and keeps rhythm in proportion as the viewport changes. A literal or a fixed --size-* in a gap stays the same size while everything around it scales.
- **size-for-controls**: Give controls (inputs, buttons) a fixed height from --size-*, at least --size-40. Or use the .btn classes, which already do. Why: A control whose height changes with the viewport is a tap target you cannot reason about. --size-* is the same number of pixels at every width.
- **radius**: Round corners with --radius-8, or --radius-full for a pill. Nothing else. Why: The site has one radius convention. --radius-4 belongs to the focus ring; the larger steps are reserve.

### Interaction

- **use-the-button**: Make buttons with the .btn classes: one colour (btn--solid, btn--ghost), one size (btn--sm to btn--xl), optionally btn--pill. Do not restyle them. Why: Shape, colour and size are three separate decisions, already made and contrast-checked. A hand-styled button is a second button.
- **focus-ring**: Keep the global :focus-visible ring. Never remove an outline, and do not restyle focus. Why: The ring is a 2px --brand-primary outline at 6.13:1 against the page, set once in reset.scss. Removing it was a WCAG failure this site has already fixed once.
- **motion**: Animate with --duration-* and --ease only, and switch the motion off inside @media (prefers-reduced-motion: reduce). Why: One easing curve and five durations, all named. Every transition on the site sits behind a reduced-motion guard.
- **one-breakpoint**: Let the fluid tokens do responsive work. If a layout must change, use the one breakpoint, max-width 767px. Custom properties do not work inside @media. Why: One breakpoint is enough because every size and space between 390 and 1920px is already fluid. The breakpoints were once converted to custom properties, which silently disabled all seven.
- **layers**: Do not add stacking contexts. If something must sit above, use --z-content or --z-header. Why: The whole site has two layers. A third should be a conversation, not a commit.

### Accessibility

- **labelled-inputs**: Give every input a visible <label> tied to it with for/id, or wrapping it. A placeholder is not a label. Why: A placeholder disappears as soon as someone types, and screen readers treat it inconsistently. A visible label is the only label everyone gets.
- **input-text**: Set the text inside an input to --p-lg, which never drops below 16px. Why: Form controls do not inherit the body size, and iOS Safari zooms the whole page when a field with text under 16px takes focus.

## Colour roles

The semantic layer: the only colours a component may use. Reserve tokens are marked; do not use them.

### Surfaces

Grounds. --surface-primary is the page. --surface-muted is a quiet panel for asides and callouts. --surface-brand is the tinted case-study panel; copy on it uses the --text-on-brand* tokens, never the plain text tokens.

| Token | Resolves to | Status | Used for |
| --- | --- | --- | --- |
| `--surface-primary` | #fcfcfc | active | the page ground |
| `--surface-secondary` | #09090b | reserve | — |
| `--surface-tertiary` | #62748E | reserve | — |
| `--surface-inverse` | #09090b | reserve | — |
| `--surface-muted` | #f0f7f0 | active | was --surface-green, a raw hex declared in this file · .cs-tradeoff, .cs-reflect, and the editorial page ground |
| `--surface-brand` | #a0fadd | active | the tinted panel ground of the case-study layer · .cs-meta-rail, .cs-glance |

### Text

Copy on the page ground. --text-primary for body copy, --text-strong for labels and kickers, --text-muted for metadata, --text-secondary for a label on an accent fill. --text-disabled is for non-interactive items only; it is too light for anything a person needs to read.

| Token | Resolves to | Status | Used for |
| --- | --- | --- | --- |
| `--text-primary` | #09090b | active | all body copy |
| `--text-secondary` | #fcfcfc | active | text on a dark or accent-filled ground · the pill CTA label |
| `--text-tertiary` | #1D293D | reserve | — |
| `--text-inverse` | #CAD5E2 | reserve | repointed from the dead --cool-gray-300 in 9802307 · became unreachable when .design-system was retired |
| `--text-strong` | #0F172B | active | near-black section labels, a step lighter than body copy · .cs-kicker |
| `--text-muted` | #45556C | active | .cs-piece metadata |
| `--text-disabled` | #62748E | active | the non-interactive nav item |

### Accent (rose)

Interaction and attention: the button fill, rules, bullets, markers, and the focus ring. --accent at rest, --accent-strong on hover. Do not use it for large fills or body copy.

| Token | Resolves to | Status | Used for |
| --- | --- | --- | --- |
| `--accent` | #be123c | active | — |
| `--accent-subtle` | #fda4af | reserve | a placeholder marker has to be legible to work as a warning. --rose-300 on --surface-brand measured 1.55:1, so .cs-stat .n was repointed to --accent (5.15:1) in 2026-09 and this went to reserve |
| `--accent-strong` | #9f1239 | active | the accent one step down, for hover · solid and ghost button hover |
| `--brand-primary` | #be123c | active | reconciled 2026-09. Was --rose-500, which made the focus ring the one place the "brand" colour appeared while --rose-700 carried every visible accent. Also raises the ring against --surface-primary from 3.58:1 to 6.13:1 · the global :focus-visible ring |

### Brand support (teal)

The case-study chrome. --text-brand* is teal on the page ground; --text-on-brand* is copy sitting on --surface-brand. --brand-mark is a mark, not text.

| Token | Resolves to | Status | Used for |
| --- | --- | --- | --- |
| `--brand-mark` | #00d2aa | active | the .cs-kicker dash |
| `--text-brand` | #006759 | active | .cs-eyebrow |
| `--text-brand-emphasis` | #006759 | active | emphasis inside a callout, on --surface-muted. Darkened from --teal-700 in 2026-09: the contrast table on /design-system caught it at 4.30:1, under AA for body copy. Now 6.25:1 · .cs-tradeoff <strong> |
| `--text-on-brand` | #00554b | active | meta-rail terms and definitions |
| `--text-on-brand-strong` | #00302b | active | glance and stat labels |
| `--text-on-brand-muted` | #006759 | active | de-emphasised copy on --surface-brand. Darkened from --teal-700 in 2026-09 (3.84:1, under AA). Now 5.58:1, still a visible step lighter than --text-on-brand. Same value as --text-brand-emphasis but a different role; they may diverge · meta-rail placeholders |

### Borders

--border at rest, --border-strong on hover, --border-dashed for frames and placeholders, --border-rule for a full-width rule.

| Token | Resolves to | Status | Used for |
| --- | --- | --- | --- |
| `--border` | #CAD5E2 | active | .cs-piece at rest |
| `--border-strong` | #62748E | active | .cs-piece on hover |
| `--border-dashed` | #90A1B9 | active | the .cs-tradeoff border, and the dashed frames on /design-system |
| `--border-rule` | #45556C | active | the footer's top rule |

## Contrast

Computed from resolved values. Body copy needs AA (4.5:1). "AA non-text" clears 3:1 only: right for a focus ring or a border, wrong for text.

| Text | On | Ratio | Grade | Where |
| --- | --- | --- | --- | --- |
| `--text-primary` | `--surface-primary` | 19.39:1 | AAA | Body copy on the page |
| `--text-strong` | `--surface-primary` | 17.38:1 | AAA | Section kickers |
| `--text-muted` | `--surface-primary` | 7.39:1 | AAA | Card metadata |
| `--text-disabled` | `--surface-primary` | 4.64:1 | AA | The inactive nav item |
| `--text-brand` | `--surface-primary` | 6.64:1 | AA | The case-study eyebrow |
| `--accent` | `--surface-primary` | 6.13:1 | AA | Accent copy and the focus ring |
| `--text-secondary` | `--accent` | 6.13:1 | AA | Button label, at rest |
| `--text-secondary` | `--accent-strong` | 7.81:1 | AAA | Button label, on hover |
| `--text-on-brand` | `--surface-brand` | 7.17:1 | AAA | Meta-rail terms and definitions |
| `--text-on-brand-strong` | `--surface-brand` | 11.81:1 | AAA | Glance and stat labels |
| `--text-on-brand-muted` | `--surface-brand` | 5.58:1 | AA | Meta-rail placeholders |
| `--text-primary` | `--surface-muted` | 18.25:1 | AAA | Copy inside a callout |
| `--text-brand-emphasis` | `--surface-muted` | 6.25:1 | AA | Emphasis inside a callout |
| `--accent` | `--surface-brand` | 5.15:1 | AA | Placeholder markers on a panel |

## Type

Font sizes come from this ramp only. Headings in a component usually step down to `--h6` or `--h5`; `--h1` to `--h3` are page-level.

| Token | Range | Status | Used for |
| --- | --- | --- | --- |
| `--h1` | 32px → 72px | active | 32 → 72px |
| `--h2` | 28px → 64px | active | 28 → 64px |
| `--h3` | 24px → 56px | active | 24 → 56px |
| `--h4` | 22px → 52px | active | 22 → 52px. Recomputed 2026-09: the previous curve (32 → 48px) had a minimum larger than --h3's and --h2's, so a CMS h4 outranked an h3 on every phone. The old curve was not wrong, only misnamed — it survives as --display-sm below |
| `--h5` | 20px → 48px | active | 20 → 48px |
| `--h6` | 16px → 36px | active | 16 → 36px |
| `--display-sm` | 32px → 48px | active | 32 → 48px. The pre-2026-09 --h4 curve, renamed for what it actually does. Used by the mobile overlay nav and the glance stats |
| `--p-lg` | 16px → 24px | active | 16 → 24px · .p-lg |
| `--p` | 14px → 20px | active | 14 → 20px. The default body size |
| `--p-sm` | 14px → 16px | active | 14 → 16px · .p-sm, meta-rail terms, figure captions |

| Weight | Value | Used for |
| --- | --- | --- |
| `--fw-400` | 400 | headings, nav, pull-quotes |
| `--fw-500` | 500 | the global default, set on * |
| `--fw-600` | 600 | links, definitions |
| `--fw-700` | 700 | bold, eyebrows, kickers, titles |
| `--fw-800` | 800 | glance stat figures |

| Line height | Value | Used for |
| --- | --- | --- |
| `--lh-s` | 1.1em | headings |
| `--lh-m` | 1.2em | glance copy, pull-quotes |
| `--lh-l` | 1.4em | body copy |

## Space and size

`--space-*` is fluid, for padding, margin and gap. `--size-*` is fixed, for control heights, hairlines and icon boxes.

| Space | Range | Used for |
| --- | --- | --- |
| `--space-4` | 2px → 4px | 2 → 4px · badge and bar-row gutters on /design-system |
| `--space-8` | 4px → 8px | 4 → 8px |
| `--space-12` | 8px → 12px | 8 → 12px · media captions |
| `--space-16` | 8px → 16px | 8 → 16px |
| `--space-20` | 10px → 20px | added in 9802307 to resolve a gap in the ladder. Recomputed 2026-09: it was the one clamp in the system not solved from the 390–1920px formula, and overshot its floor by 0.1px · .cs-aside bullet indent |
| `--space-24` | 12px → 24px | 12 → 24px · the most-used spacing step |
| `--space-32` | 16px → 32px | 16 → 32px · the content-container rhythm |
| `--space-48` | 24px → 48px | 24 → 48px |
| `--space-64` | 32px → 64px | 32 → 64px · the content-container's bottom pad |
| `--space-80` | 60px → 80px | 60 → 80px · the framed-video mat, the .next bottom padding |

| Size | Value | Used for |
| --- | --- | --- |
| `--size-1` | 0.0625rem | hairline · meta-rail gutters |
| `--size-2` | 0.125rem | meta-rail and .cs-meta gutters |
| `--size-4` | 0.25rem | the .next link's internal gap |
| `--size-12` | 0.75rem | added in 9802307 to resolve a gap in the ladder · .cs-piece metadata label |
| `--size-14` | 0.875rem | .cs-piece link, footer copyright |
| `--size-16` | 1rem | the fixed-position body span |
| `--size-20` | 1.25rem | the header logo/title gap |
| `--size-24` | 1.5rem | header and nav gutters |
| `--size-32` | 2rem | small button height, mobile overlay nav label |
| `--size-40` | 2.5rem | medium button height |
| `--size-48` | 3rem | large button height |
| `--size-60` | 3.75rem | added in 9802307 to resolve a gap in the ladder · the pill CTA height, the compact header logo |
| `--size-72` | 4.5rem | the swatch chip on /design-system |
| `--size-80` | 5rem | the header logo |

| Radius | Range | Used for |
| --- | --- | --- |
| `--radius-4` | 2px → 4px | 2 → 4px · the focus ring |
| `--radius-8` | 2px → 8px | 2 → 8px. The site's one radius convention; 9802307 migrated the old --radius-sm onto it |
| `--radius-full` | 62rem | a pill, not a scale step · the CTA button |

## Motion and layers

| Token | Value | Used for |
| --- | --- | --- |
| `--duration-fast` | 0.2s | .cs-piece border and lift |
| `--duration-quick` | 0.25s | the "view case study" arrow |
| `--duration-base` | 0.3s | the next-project link |
| `--duration-slow` | 0.6s | the project-card image scale |
| `--duration-reveal` | 0.7s | the scroll-reveal fade and rise |
| `--ease` | ease-out | the only easing curve in the system |
| `--z-content` | 10 | lifts copy above a full-bleed figure · .metadata-container |
| `--z-header` | 30 | the mobile nav overlay, above everything · header.nav-open |

## Components

Buttons are classes, not a component you need to import. Compose one colour, one size and optionally a shape: `class="btn btn--solid btn--lg"`. Colours: `btn--solid`, `btn--ghost`. Sizes: `btn--sm` (32px), `btn--md` (40px), `btn--lg` (48px), `btn--xl` (60px, the site CTA). Shape: `btn--pill`.

Layout is three nested elements: `section.section-container` (full bleed) > `div.content-container` (92%, max 1400px) > `div.metadata-container` (80%, max 960px, the reading measure).

## Reserve tokens: do not use

89 tokens are defined and kept on purpose but have no job. Using one is a design decision; ask first.

`--surface-secondary`, `--surface-tertiary`, `--surface-inverse`, `--text-tertiary`, `--text-inverse`, `--accent-subtle`, `--transparent`, `--highlight-100`, `--highlight-500`, `--highlight-700`, `--rose-50`, `--rose-100`, `--rose-200`, `--rose-300`, `--rose-400`, `--rose-500`, `--rose-600`, `--rose-900`, `--rose-950`, `--teal-50`, `--teal-100`, `--teal-300`, `--teal-400`, `--teal-600`, `--teal-700`, `--blue-50`, `--blue-100`, `--blue-200`, `--blue-300`, `--blue-400`, `--blue-500`, `--blue-600`, `--blue-700`, `--blue-800`, `--blue-900`, `--blue-950`, `--gray-50`, `--gray-100`, `--gray-200`, `--gray-700`, `--gray-800`, `--gray-950`, `--white-alpha-10`, `--white-alpha-20`, `--white-alpha-30`, `--white-alpha-40`, `--white-alpha-50`, `--white-alpha-60`, `--white-alpha-70`, `--white-alpha-80`, `--white-alpha-90`, `--black-alpha-10`, `--black-alpha-20`, `--black-alpha-30`, `--black-alpha-40`, `--black-alpha-60`, `--black-alpha-70`, `--black-alpha-80`, `--black-alpha-90`, `--gradient-blue`, `--shadow-sm`, `--shadow-base`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`, `--shadow-inner`, `--size-0`, `--size-1half`, `--size-8`, `--size-18`, `--size-64`, `--size-100`, `--size-120`, `--size-160`, `--space-72`, `--space-120`, `--space-160`, `--space-240`, `--radius-16`, `--radius-24`, `--sans-alt`, `--serif-alt`, `--lh-xs`, `--lh-xl`, `--fw-100`, `--fw-200`, `--fw-300`, `--fw-900`
