Design System

# Design System Changelog

Every change to the design system is recorded here — no silent updates.
Builders: read this before starting any build work. Each entry tells you exactly which file and section to re-read.

---

**2026-07-02 — Rule deduplication: anatomy.md now points to DESIGN.md for rules**

No design rule changed. This is a structural correction implementing ADR-011
("one home per truth"): rules live only in `DESIGN.md`; `anatomy.md` holds only
measurements, token assignments, and structural specs.

**What changed:**
- Removed restatements of the two-button order rule and the behavioral label rule
  from the HeroFixed component row, the HeroFixed shell spec, and the CtaFixed
  shell spec. Each location now points to `DESIGN.md` → Buttons.
- Rationale: duplicated rules drifted before (see 2026-06-06 "Three errors
  corrected" entry) — restating a rule in two files is how contradictions happen.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 4 → Buttons (unchanged — still the single home for all button rules)
- `design-system/components/anatomy.md` → HeroFixed / CtaFixed specs

**Builder action required:** none — no rule values changed. When you need a button
rule, read it in `DESIGN.md`; never copy rules into other design-system files.

**Figma status:** No Figma change — documentation structure only.

---

**2026-06-12 — Mobile and tablet responsive QA pass**

The homepage, `/case-studies`, and `/design-system` pages were tightened for
phone and tablet review.

**What changed:**
- Removed forced 300px/240px minimum card widths from landing, case-study, and
  design-system specimen cards so cards can collapse inside narrow phone
  content widths.
- Kept the real site navigation in mobile-menu mode through tablet widths, so
  the expanded Case Studies nav does not crowd the header.
- Changed case-study proof grids to use 2 columns on tablet and 3 columns only
  on larger desktop screens.
- Added phone/tablet CSS adjustments for section spacing, hero/type scale,
  case-study preview density, and touch hover behavior.
- Tightened design-system specimen grids and spacing bars so the documentation
  page no longer teaches desktop-only card behavior on small screens.
- Clarified the design-system card-width rule: 300px is a desktop/tablet visual
  target only; phone layouts must allow `min-width: 0` or equivalent.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Cards / Responsive Behavior / Component Prompts
- `design-system/components/anatomy.md` → Layout Rules
- `design-system/components/react-tailwind-reference.tsx` → Card / ServiceGridShell
- `site/src/app/globals.css`
- `site/src/components/NavBar.tsx`
- `site/src/app/page.tsx`
- `site/src/app/case-studies/page.tsx`
- `site/src/app/design-system/page.tsx`
- `site/src/components/LeadCaptureDialog.tsx`

**Figma status:** Responsive implementation QA. No new live Figma extraction.

---

**2026-06-12 — Design-system page left rail added**

The live `/design-system` page now has internal navigation so reviewers can
jump through the page without scrolling through every section manually.

**What changed:**
- Added a left rail "On this page" menu on desktop.
- Added horizontal overflow navigation for smaller screens.
- Added section anchor IDs for Foundation, Typography, Geometry, Layout,
  Navigation, Buttons & Pills, Cards, Interactions, Composition, Footer, and
  Changelog.
- Updated the case-study card specimen to use the same populated
  `CasePreviewVisual` component as the live homepage and `/case-studies` page.

**Where to find it — builder must re-read these:**
- `site/src/app/design-system/page.tsx`
- `site/src/components/CasePreviewVisual.tsx`

**Figma status:** Documentation-page usability update only. No new live Figma
extraction.

---

**2026-06-12 — Case Studies navigation and proof route added**

The premium landing navigation now includes a Case Studies link, and the proof
section routes to a dedicated case-study cover page.

**What changed:**
- Added Case Studies to the documented premium nav link set.
- Updated nav anchors to root-prefixed links so they work from `/` and from
  supporting pages such as `/case-studies`.
- Removed the homepage "Not sure where to start?" section from the current
  landing-page structure.
- Added `/case-studies` as the portfolio cover page destination for proof-card
  actions and section CTAs.

**Where to find it — builder must re-read these:**
- `design-system/components/anatomy.md` → Premium Fixed Navigation
- `site/src/components/NavBar.tsx`
- `site/src/app/page.tsx` → CaseStudies / Home render order
- `site/src/app/case-studies/page.tsx`
- `docs/context/pages/home.md`
- `docs/context/strategy/information-architecture.md`

**Figma status:** Product/navigation decision layered onto the Figma Make
landing style. No new live Figma extraction.

---

**2026-06-12 — Figma Make requirement audit linked**

The design-system README now points to a single audit file that maps the
original Figma Make style-guide request to the local files that implement or
document it.

**What changed:**
- Added `docs/core/figma-make-design-system-audit.md`.
- Linked the audit from `design-system/README.md`.
- Added the audit to the design-system read order so future builders check
  source locations, coverage, and remaining unproven items before making more
  Figma Make-style changes.

**Where to find it — builder must re-read these:**
- `docs/core/figma-make-design-system-audit.md`
- `design-system/README.md` → Figma Make Landing Style Quick Start

**Figma status:** Documentation and traceability update only. Live Figma MCP
pixel proof remains unproven.

---

**2026-06-11 — Premium token bridge consistency fixed**

The premium landing tokens are now more consistently exposed across JSON, CSS, and the Tailwind bridge.

**What changed:**
- Added `h-9` and `h-10` to `design-system/tokens/tokens.json` so fixed button heights are part of the structured token export.
- Added `nav-backdrop-bg` to `tokens.json` layout tokens so premium fixed navigation can be rebuilt from structured tokens.
- Expanded `design-system/tokens/tailwind-theme.ts` with detailed gap, padding, height, and premium nav/footer layout token mappings.
- Updated the site token sync comment in `site/src/app/globals.css` to `2026-06-11`.

**Where to find it — builder must re-read these:**
- `design-system/tokens/tokens.json`
- `design-system/tokens/tailwind-theme.ts`
- `site/src/app/globals.css`

**Figma status:** Token bridge update only; no visual change.

---

**2026-06-11 — React Tailwind reference updated for Figma Make shells**

The React/Tailwind reference file now reflects the richer Figma Make landing patterns instead of only the older base shells.

**What changed:**
- Added `hero-primary` button variant to the reference button component.
- Added `industry-tag`, `premium`, `service-grid-card`, and `faq-accordion` reference variants.
- Updated `Section` alternate tone to use `section-alternate-premium`.
- Added `NavBarPremium` reference with fixed translucent shell, desktop links, and mobile hamburger/close dropdown state.
- Added hero underline and hero-primary CTA usage to `HeroFixed`.
- Added `ServiceGridShell` reference for the six-card "What I offer" pattern.

**Where to find it — builder must re-read these:**
- `design-system/components/react-tailwind-reference.tsx`
- `design-system/components/anatomy.md` → Figma Make Landing Anatomy
- `design-system/components/variants.md` → Button, Card, Layout Shells

**Figma status:** Reference reflects the extracted Figma Make package and current local implementation.

---

**2026-06-11 — Builder quick start added for Figma Make style replication**

The design-system entry docs now explain how to reuse the extracted Figma Make landing style on future pages.

**What changed:**
- Added a Figma Make Landing Style Quick Start to `design-system/README.md`.
- Added a Figma Make Page Replication Checklist to `DESIGN.md`.
- Documented the exact read order for future builders and the required page-level style characteristics: premium nav, hero treatment, section rhythm, service grid, case-study cards, trust editorial section, lead capture, chat, CTA, and footer.
- Updated `DESIGN.md` last-updated date.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Figma Make Page Replication Checklist
- `design-system/README.md` → Figma Make Landing Style Quick Start
- `design-system/components/anatomy.md` → Figma Make Landing Anatomy
- `site/src/app/design-system/page.tsx` → live preview

**Figma status:** Documentation uses the extracted Figma Make package and current local implementation as evidence.

---

**2026-06-11 — FooterFixed implemented in homepage and preview**

The homepage footer now follows the extracted Figma Make footer structure instead of the reduced two-column local version.

**What changed:**
- Updated homepage footer to four columns: brand block, Services, Learn More, and Legal.
- Kept FooterFixed on `--background` with a `--secondary` divider and centered muted copyright row.
- Added a FooterFixed specimen to `/design-system`.
- Added a homepage content contract for footer anatomy and link behavior.
- Corrected a stale project-log checklist item that still referenced the wrong muted footer background.

**Where to find it — builder must re-read these:**
- `site/src/app/page.tsx` → `Footer`
- `site/src/app/design-system/page.tsx` → Footer Anatomy
- `docs/context/pages/home.md` → Footer
- `docs/core/project-log.md` → QA Notes / old checklist correction

**Figma status:** Sourced from the extracted Figma Make footer structure; surface color follows the approved repo rule that FooterFixed always uses `--background`.

---

**2026-06-11 — Service grid shell restored from Figma Make**

The service/offer section now uses the richer six-card service-grid pattern from the extracted Figma Make landing page instead of the reduced three-pillar summary.

**What changed:**
- Homepage Services section changed to "What I offer" with six premium cards: UX Audits, Information Architecture, Tactical UX Design, Design System Guidance, Research & Prioritization, and Stakeholder Coaching.
- Added `service-grid-card` and `ServiceGridShell` to component variant/anatomy docs.
- Added a compact Service Grid Shell specimen to `/design-system` so the grid can be visually inspected.
- Updated homepage content context so future builders keep the six-card grid and CTA pattern.

**Where to find it — builder must re-read these:**
- `site/src/app/page.tsx` → `services` and `WhatIDeliver`
- `site/src/app/design-system/page.tsx` → Service Grid Shell specimen
- `design-system/components/anatomy.md` → Service Grid Shell
- `design-system/components/variants.md` → `service-grid-card`, `ServiceGridShell`
- `docs/context/pages/home.md` → Section 5

**Figma status:** Sourced from the extracted Figma Make `services` array and What I Offer section.

---

**2026-06-11 — Navigation preview anatomy corrected**

The live `/design-system` navigation preview now matches the documented and implemented mobile menu pattern.

**What changed:**
- Replaced the incorrect mobile chevron sample with the hamburger/open and X/close states used by the landing-page navigation.
- Expanded the preview with desktop anatomy notes: translucent fixed shell, bottom-aligned logo/nav baseline, muted link row, and single filled schedule CTA.
- Added a mobile open-state preview showing stacked links, full-width CTA, and the close icon.

**Where to find it — builder must re-read these:**
- `site/src/app/design-system/page.tsx` → Navigation And Header
- `design-system/components/anatomy.md` → Premium Fixed Navigation
- `site/src/components/NavBar.tsx` → actual mobile menu implementation

**Figma status:** Matches the extracted Figma Make navigation pattern and current local implementation.

---

**2026-06-08 — Figma Make premium landing style documented**

The Figma Make UX Consultant Landing Page style has been added as an approved richer landing-page layer on top of the existing BPB design system.

**What changed:**
- Added Figma Make-style premium navigation rules: fixed translucent backdrop, large logo height tokens, derived nav height, hero offset, desktop link row, and mobile hamburger/dropdown interaction.
- Added premium card state: base card surface remains restrained, while hover may move up 2px, shift to a purple-tinted border, and use `--card-premium-hover`.
- Added Figma Make-style alternate section treatment: `--section-alternate-gradient` from `--section-alternate-start` (#f6f7f9) to `--section-alternate-end` (#f1f3f7).
- Added hero CTA tokens: `--gradient-hero-button`, `--gradient-hero-button-hover`, and `--button-premium-hover`.
- Added responsive hero display behavior in code: 44px desktop, 40px tablet, 32px small mobile.
- Added controlled footer logo sizing tokens: `--logo-footer-width` and `--logo-footer-height`.
- Added component anatomy for FAQ accordion cards, industry tags, avatar treatment, premium hero behavior, and premium fixed navigation.
- Added component anatomy and preview coverage for the Figma Make request-information dialog and floating chat widget.
- Added `DESIGN.md` component rules for Lead Capture Dialog and Chat Widget.
- Synced `design-system/tokens/tokens.json` typography values with the existing June 7 typography update.
- The Figma Make cyan/secondary gradient family was intentionally not imported; purple remains the only brand accent direction.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 2: Color Palette & Roles → Supporting Surfaces and CTA Gradient
- `DESIGN.md` → Section 4: Component Stylings → Buttons, Pills, Cards, Sections, NavBar
- `DESIGN.md` → Section 4: Component Stylings → Lead Capture Dialog and Chat Widget
- `design-system/components/anatomy.md` → Figma Make Landing Anatomy
- `design-system/components/variants.md` → Button, Pill, Card, Layout Shells
- `design-system/components/typography.md` → Figma Make Hero Responsiveness
- `design-system/tokens/tokens.css` → premium landing tokens
- `design-system/tokens/tokens.json` → premium landing tokens and synced typography values
- `design-system/tokens/tailwind-theme.ts` → premium token bridge
- `design-system/tokens/tailwind-theme.ts` → gradient background-image bridge

**Builder action required:**
- Update the landing page to use the premium fixed navigation, hero offset, Figma Make-style alternate section gradient, premium card hover state, industry tag hover state, FAQ accordion card pattern, avatar treatment, and final CTA treatment.
- Keep the implementation tokenized; do not copy hardcoded Figma Make CSS values directly into page components.
- Do not introduce the Figma Make cyan/secondary gradient family unless Susanne separately approves a second accent direction.

**Figma status:** Updated in Figma Make prototype — sourced from `UX Consultant Landing Page`

---

**2026-06-07 — Typography tokens updated from new token sheet; typography.md created**

Six type classes updated with new line-heights and weights from the revised token sheet. Values are now expressed as ratios (1.4×, 1.6×) aligned with the new sheet. Font-family fallback stack expanded. A dedicated `typography.md` reference file created.

**What changed:**
- `type-heading-3`: line-height 41.6px (1.9×) → 30.8px (1.4×). The extreme 1.9× ratio was the only value the new sheet clearly contradicts — size (22px) and weight (400) unchanged.
- `type-heading-4`: weight 600 (SemiBold) → 500 (Medium); line-height 28px (1.56×) → 25.2px (1.4×)
- `type-body-md`: line-height 26px → 25.6px (now matches body-sm exactly, both 1.6×)
- `type-label-lg`: weight 700 (Bold) → 500 (Medium); line-height 24px → 22.4px (1.4×)
- `type-label-sm`: line-height 18px (1.5×) → 16.8px (1.4×)
- `type-text-sm-medium`: line-height 20px → 19.6px (1.4×)
- Font-family fallback: added Roboto, Oxygen, Ubuntu, Cantarell; removed ui-sans-serif, system-ui
- New file: `design-system/components/typography.md` — dedicated type reference with full spec table, shell usage map, and line-height/tracking rationale

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 3: Typography Rules → Type Scale table
- `design-system/components/typography.md` → full reference (new file — read this first)
- `site/src/app/globals.css` → Typography utilities section
- `design-system/tokens/tokens.css` → type-* classes

**Builder action required:**
- `type-heading-4` is now Medium (500), not SemiBold — update any hardcoded weight overrides
- `type-label-lg` is now Medium (500), not Bold — button labels are now slightly lighter
- `type-body-md` and `type-body-sm` are now identical (both 400/16px/25.6px) — use either for standard body copy
- Read `design-system/components/typography.md` before implementing any text-heavy component

**Figma status:** Not yet updated in Figma — Susanne to sync token values

---

**2026-06-06 — Three errors corrected: FooterFixed token, CTA prohibition, Section variant names**

Three contradictions introduced by a parallel agent session have been corrected. No design rules changed — these are documentation corrections only.

**What changed:**
- `anatomy.md` Components table, Section row: "FooterFixed always uses `--muted`" corrected to "FooterFixed always uses `--background` (#ffffff)" — this directly contradicted the FooterFixed Shell Specification in the same file and DESIGN.md
- `DESIGN.md` Sections → Hard rules: restored the explicit prohibition "Never use the `CTA` section to promote a tool, a newsletter, or any secondary interest — it is reserved exclusively for booking and hire actions." This rule was present earlier in the session and was dropped by another agent.
- `react-tailwind-reference.tsx` Section component: renamed variant values to match canonical DESIGN.md names. `"muted"` → `"alternate"`, `"gradient"` → `"CTA"`. Removed `"primary"` (no such section variant exists). Fixed CTA implementation: removed incorrect `bg-primary text-secondary-foreground` base class; CTA gradient is applied via absolute overlay only.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 4: Component Stylings → Sections → Hard rules
- `design-system/components/anatomy.md` → Components table → Section row
- `design-system/components/react-tailwind-reference.tsx` → Section component

**Builder action required:**
- FooterFixed background is `--background` (#ffffff) — never `--muted`
- CTA section is for booking/hire only — never tools, newsletters, or secondary interests
- Section `tone` prop accepts: `"default"` | `"alternate"` | `"secondary"` | `"CTA"` — no other values

**Figma status:** No Figma change required — these were documentation and code errors, not design changes

---

**2026-06-06 — CtaFixed button order corrected; surface-aware button hierarchy documented**

The CtaFixed button positions were documented backwards. Figma (node 326:2667) is the source of truth.

**What changed:**
- LEFT button (secondary): `tertiary` variant — `--background` fill, `--primary` border+text — "Schedule a quick call"
- RIGHT button (primary): `inverted` variant — no fill, `--secondary-foreground` border+text — "Connect on Linkedin"
- New rule documented: the button *variant* changes to suit the surface, but primary is ALWAYS right, secondary ALWAYS left. This is called the surface-aware button hierarchy.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 4: Component Stylings → Buttons → "Surface-aware button hierarchy" table
- `design-system/components/anatomy.md` → Shell Specifications → CtaFixed → CTA row
- `design-system/components/variants.md` → Button Layout Rule section

**Builder action required:**
- When building CtaFixed: inverted (no fill, `--secondary-foreground`) on the RIGHT, tertiary (white fill, `--primary` border) on the LEFT
- On white/light surfaces: primary variant (purple fill) on RIGHT, secondary/tertiary on LEFT
- These are not interchangeable — the surface determines the variant, the rule determines the position

**Figma status:** Confirmed in Figma node 326:2667

---

**2026-06-06 — FooterFixed background corrected to `--background` (#ffffff)**

FooterFixed was incorrectly documented as `--muted` earlier in this session. Corrected.

**What changed:**
- FooterFixed background: `--muted` → `--background` (#ffffff, pure white)
- Rule: NavBar, Hero section, and FooterFixed all always use `--background`. No exceptions.

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 4: Component Stylings → Sections → Hard rules
- `DESIGN.md` → Section 4: Component Stylings → Sections → Section Ordering Rules → rule 5
- `design-system/components/anatomy.md` → Shell Specifications → FooterFixed → Background
- `design-system/components/variants.md` → Layout Shells → FooterFixed

**Builder action required:**
- FooterFixed background must be `bg-background` or `background-color: var(--background)` — never `bg-muted`
- This is not yet built — apply when building FooterFixed

**Figma status:** Not confirmed in Figma — background not explicitly set in shell component

---

**2026-06-06 — Button layout and behavioral label rules added**

Two new universal rules documented for all button rows across all shells.

**What changed:**
- Rule 1: In any two-button row, secondary action is LEFT, primary action is RIGHT. No exceptions.
- Rule 2: Button labels must be behavioral, not destination names. "How can we work together" not "View services". "Let's talk" not "Contact".
- HeroFixed button row documented (was missing entirely). Note: button row is also missing from Figma — Susanne to add.
- CtaFixed button order documented (later corrected — see entry above).

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 4: Component Stylings → Buttons → "Two-button row layout rule"
- `DESIGN.md` → Section 4: Component Stylings → Buttons → "Button label rule"
- `DESIGN.md` → Section 6: AI Generation Notes → What NOT to Do (last 3 rules)
- `design-system/components/anatomy.md` → Shell Specifications → HeroFixed → Button row
- `design-system/components/variants.md` → Button Layout Rule section

**Builder action required:**
- Never place the primary button on the left
- Never label a button with a page name — always describe the action or outcome
- HeroFixed must include a button row: secondary left, primary right

**Figma status:** Button row missing from HeroFixed in Figma — Susanne to add

---

**2026-06-06 — Shell specifications added to anatomy.md from Figma**

Full layout specifications sourced directly from Figma for all four fixed shells.

**What changed:**
- New section "Shell Specifications" added to `anatomy.md` with full Figma-sourced specs for NavBar, HeroFixed, CtaFixed, FooterFixed
- Each spec includes: Figma node ID, width, spacing tokens, typography classes, color tokens, element order
- Section divider rule added: `--divider-sm` (0.63px) in `--border` between all sections
- CTA section purpose rule added: must appear on every page, always promotes booking/hire action, always directly above footer
- Secondary section tightened: valid only for pricing tables, comparison data, highlighted specs — not text, cards, or media

**Where to find it — builder must re-read these:**
- `design-system/components/anatomy.md` → Shell Specifications (full section — NavBar, HeroFixed, CtaFixed, FooterFixed)
- `design-system/components/anatomy.md` → Section Divider
- `DESIGN.md` → Section 4: Component Stylings → Sections → Hard rules (CTA purpose rule)
- `DESIGN.md` → Section 2: Color Palette → Supporting Surfaces (secondary section description)

**Builder action required:**
- Before building any shell, read its full spec in `anatomy.md` → Shell Specifications
- Apply `--divider-sm` border between every section
- CTA section must appear on every page — it is not optional

**Figma status:** Specs sourced from Figma nodes: NavBar 397:3247, HeroFixed 326:2936, CtaFixed 326:2667, FooterFixed 344:1730

---

**2026-06-05 — Section variant token assignments corrected**

Corrected a documentation mistake in the section variant definitions. No token values or visual colors changed.

**What changed:**
- `alternate` variant: correctly mapped to `--muted` (#fafafa) — the nearly-white subtle alternating background
- `secondary` variant: correctly mapped to `--secondary` (#e2e8f0) — the slightly darker blue-gray, reserved for structured content sections only; not part of the alternating rhythm

**Where to find it — builder must re-read these:**
- `DESIGN.md` → Section 4: Component Stylings → Sections → variants table
- `design-system/components/anatomy.md` → Components table → Section row

**Builder action required:**
- `alternate` sections use `--muted` (#fafafa) — not `--secondary`
- `secondary` sections use `--secondary` (#e2e8f0) — reserved for tables/data only, not cards or text

**Figma status:** Confirmed correct in Figma token values

---

## 2026-05-29 — Initial Figma Design System Export

**What changed**
- Created the first code-side design system export from the Figma `Design System` section.
- Added token files for colour, typography, spacing, radii, borders, shadows, and layout values.
- Added component anatomy and variant documentation.
- Added a React + Tailwind reference implementation for the future Next.js app.

**Why**
- The Figma source is now tokenized enough to become the code source of truth.
- The website build needs stable tokens and component definitions before page implementation begins.

**Affects**
- `design-system/tokens/`
- `design-system/components/`
- Future Next.js + Tailwind app scaffold

**Notes**
- Final audit before export found 0 production colour binding issues.
- The section gradient remains a Figma gradient paint and is represented in code as `--gradient-01`.