pbakaus_impeccable/docs/design-context-categorization/CONTENTS.md

# Contents

What currently produced output (`PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`) maps to, category by category, against the proposed 8-category design context doc.

Source examples analyzed (local scratch runs, not tracked in this repo):

- `tmp/notes/init-tests/runs/noren-ops-20260708-1832/DESIGN.md` + `proof/PRODUCT.md` + `proof/design.json`
- `tmp/notes/init-tests/runs/hanazono-atelier-20260708-1832/DESIGN.md` + `/Users/abdulwahab/hanazono-atelier/PRODUCT.md`

Every field below also has a provenance — derived from code, or from one of three questionnaire flows (in-chat during init, in-chat during document, browser during document — the last two cover both what's shipped today and the new seed work). See [`PROVENANCE.md`](./PROVENANCE.md) for the mechanism and [`CONTENTS-TABLE.md`](./CONTENTS-TABLE.md) for the per-field breakdown.

---

## Audience

*Who it is for, emotional state, needs, trust triggers.*

Found in:
- `PRODUCT.md` → `## Users`
  - Primary/secondary role
  - Company context
  - Weekly rhythm
  - Job-to-be-done
- `PRODUCT.md` → `Brand Personality` → "Emotional goal on landing"
  - e.g. Hanazono: "quiet authority"
  - Filed under Brand Personality today, but it's really audience emotional state

Gap:
- No dedicated trust-trigger question in the Audience interview block. As of [PR #315](https://github.com/pbakaus/impeccable/pull/315), the *content* exists one category over — see Product → `## Conversion & proof` → "Proof on hand" — but nothing cross-references it back into Audience.
- What exists instead (Rippling/Linear, Nicolai Bergmann/Cereal) are taste anchors, not trust signals

Tightened by PR #315 (not new content, but new rigor):
- `## Users` now requires a confirmed primary/secondary split rather than an inferred one — no manufacturing a secondary audience that isn't there.
- Explicit question when the surface's audience differs from who actually uses the product (e.g. a marketing site's visitor vs. an app's daily operator).

---

## Product

*Purpose, differentiator, proof points, use cases, what must be clear first.*

Found in:
- `PRODUCT.md` → `## Product Purpose`
  - What it does
  - The success definition
- `PRODUCT.md` → `## Positioning` (added in [PR #315](https://github.com/pbakaus/impeccable/pull/315), both registers)
  - "The single strategic claim every screen reinforces"
  - This is the differentiator field, now explicit instead of buried in Design Principles
- `PRODUCT.md` → `## Conversion & proof` (added in PR #315, **brand register only** — product register omits the section, heading included)
  - Primary and secondary CTA
  - The line a visitor remembers after 10 seconds
  - Belief ladder (what a visitor must believe, in order, before the primary CTA)
  - Proof on hand: testimonials, case studies, press, client/partner logos — referenced by path, collected under `.impeccable/assets/proof/`
  - This fills the proof-points sub-item directly, and the belief ladder / memorable line fill "what must be clear first"
- Use cases — still only implicit
  - Hanazono's three commission lanes are named in Product Purpose
  - Noren's app routes (Dashboard/People/PTO/Onboarding/Settings) only show up in agent-log crawl notes, never written into `PRODUCT.md` itself
  - Untouched by PR #315

Gap:
- Proof points / conversion framing don't exist for product-register projects — `Conversion & proof` is explicitly omitted there
- Use cases remain implicit rather than an enumerated field, for both registers

Also mapped here (resolved orphans — see [`ORPHANS.md`](./ORPHANS.md)):
- **Register** (`product`/`brand`) — travels with Product Purpose as the metadata switch for the rest of the doc
- **Name** (`DESIGN.md` frontmatter `name`) — the literal project name; an identifier, not a design decision. (`description` moved to Brand — see below.)

---

## Brand

*Identity, wordmark/logo fallback, voice, tone, cues, taste boundaries, anti-references.*

Found in:
- `DESIGN.md` → `## 1. Overview`
  - Creative North Star name
  - Narrative + key characteristics
- `PRODUCT.md` → `Brand Personality`
  - Three words
  - Voice, tone
  - References
- `PRODUCT.md` → `## Anti-references`
  - Echoed in `DESIGN.md` Overview and `## 6. Do's and Don'ts`

Also mapped here (resolved orphans — see [`ORPHANS.md`](./ORPHANS.md)):
- **Design Principles** (the numbered list as a unit) — e.g. "Quiet authority over persuasion," "Restraint in every frame" read as voice/taste judgment calls, closer to Brand's cues and taste boundaries than to Product's purpose/differentiator framing. Kept intact as a unit rather than decomposed per-bullet, even though a few individual principles (e.g. "One workspace, not three spreadsheets") lean Product.
- **Description** (`DESIGN.md` frontmatter `description`) — the short form of the same Creative North Star narrative above, not a separate fact. Was bundled with `name` under Product; that was a mistake, since it's brand-identity content compressed to one sentence, not header metadata.

Gap:
- Wordmark / logo fallback is completely absent in both examples
- No logo file reference, no text-lockup rule for when no mark exists

---

## Color

*Palette, roles, tints, strategy, dark-mode inference, copyable values.*

Found in:
- `DESIGN.md` frontmatter `colors:` block → palette + copyable hex values
- `DESIGN.md` → `## 2. Colors`
  - `### Primary` / `### Neutral` → roles
  - `### Named Rules` → strategy (One Accent Rule, Humane Ground Rule, One Plum Rule, Warm Ground Rule)
- Tints
  - Hanazono: opacity variants in frontmatter (`ink-muted`, `ink-subtle`, `divider`)
  - Noren: separate flat colors instead (`surface-raised`, `border-subtle`)

Also mapped here (resolved orphan — see [`ORPHANS.md`](./ORPHANS.md)):
- **Tonal ramps** (`design.json` → `colorMeta.tonalRamp`, OKLCH 8-step ramps per color) — promoted out of the sidecar into the doc, alongside the canonical hex

Gap:
- No dark-mode palette or inference logic anywhere
- The tonal ramps could seed one (they're dark-to-light ordered already) but nothing does yet — promoting them into the doc is a first step, not the full fix

---

## Typography

*Font families, hierarchy, font scale, readability rules.*

Found in:
- `DESIGN.md` frontmatter `typography:` block + "Display Font / Body Font" callouts
- `### Hierarchy` — role, size, weight, line-height, tracking, usage per level
- Readability rules
  - ch-width caps
  - `text-wrap: balance/pretty`
  - Named Rules (One Voice Display Rule, Measure Rule, Homepage Italic Rule)

Gap:
- Best-covered category, no real gaps
- Possible exception: no explicit rule documenting non-Latin fallback rationale (Hanazono stacks Hiragino Mincho / Yu Mincho for Japanese rendering)

Planned (upcoming visual document seed, not yet shipped):
- **Typescale** — a named modular scale/ratio (base size + ratio, e.g. Major Third) that generates the hierarchy, replacing hand-picked per-role sizes with a systematic rule.

---

## Iconography

*Icon style, stroke weight, metaphor rules, icon-button behavior, allowed/forbidden icon types.*

Found in:
- Nothing today. Zero mentions in `PRODUCT.md`, `DESIGN.md`, or `design.json` for either project
- Closest adjacent item: Hanazono's don't — "no decorative floral motifs in UI chrome" — but that's illustration/decoration, not icons

Planned (upcoming visual document seed, not yet shipped):
- **Icon library/style** — a direct question ("Which icon style should the design use?") with named library options (Lucide, Tabler Icons, Hugeicons), each with a one-line fit description.

Gap:
- Library choice covers icon *style* only. Stroke weight, metaphor rules, icon-button behavior, and allowed/forbidden icon types are not part of this question and stay unfed even once it ships.

---

## Material

*Radius, borders, shadows, elevation, surfaces, folds/edges, texture, motion feel.*

Found in:
- Radius: `rounded:` frontmatter tokens / Hanazono's explicit "square corners, no border-radius"
- Borders: Border Subtle / Hairline Rule / Lane Divider / CTA Stroke
  - Their color *values* live in the Color section — Material only gets them by reference
- Shadows + elevation: `## 4. Elevation` section, backed by `design.json.shadows[]`
- Surfaces: Surface Raised is written up under Color's `### Neutral`, not a Material section
  - Functionally a Material concept, textually filed under Color
- Motion feel — scattered
  - `prefers-reduced-motion` compliance + per-component hover behavior in Do's/Don'ts and Components prose
  - Actual motion tokens (`ease-standard`, `duration-fast`) only exist in `design.json`, never surfaced in `DESIGN.md`

Gap:
- Texture/grain and folds/edges have no field, not even to declare "intentionally none"
- Both example systems are flat by doctrine, but there's no explicit material-honesty statement captured anywhere

Also mapped here (resolved orphans — see [`ORPHANS.md`](./ORPHANS.md)):
- **Spacing / layout scale** (`xs/sm/md/lg/xl/gutter/section` tokens) — physical construction of the interface, alongside radius/borders/elevation
- **Breakpoints** (`sm/md/lg` px values) — responsive behavior of the same physical system
- **Motion tokens** (`design.json` → `extensions.motion`, e.g. `ease-standard`, `duration-fast`) — promoted out of the sidecar so the doc states the real easing curve and duration, not just qualitative motion feel

Planned (upcoming visual document seed — Layout structure already exists in today's seed, just not previously captured in this analysis):
- **Layout structure / grid strictness** — "How strict should the layout feel?" with named points on a spectrum (Simple grid, Balanced, Editorial, Freeform). A rhythm/composition rule distinct from the spacing scale — this is about how strictly content aligns to a grid, not what the spacing values are.

---

## Interface

*Buttons, inputs, cards/panels, rails, tabs, swatches, copy controls, component states, interaction patterns.*

Found in:
- `DESIGN.md` frontmatter `components:` token bindings
- `## 5. Components`
  - Buttons, Chips, Cards, Inputs, Navigation
  - Signature/future components: Metric Summary, Proof Quote, Commission Lane, Consultation Form, Gallery Grid
- Component states (hover/focus/error/disabled) documented inline per component
- `design.json.components[]` → concrete HTML/CSS per component

Also mapped here (resolved orphan — see [`ORPHANS.md`](./ORPHANS.md)):
- **Accessibility & Inclusion** (`PRODUCT.md` · WCAG target, reduced motion, alt text, color-vision pairing, plain-language/bilingual notes) — kept as a unit rather than split; the majority of its actual content (keyboard nav, screen-reader behavior, focus visibility, alt text) is Interface, even though reduced motion (Material), contrast/color-vision (Color), and bilingual notes (Audience) also draw from it. Filed here instead of Material, where it originally landed.

Gap:
- Best second-covered category
- Tabs/rails/swatches/copy-controls aren't exercised by either example — reads as "not needed by these two fixtures," not "no place to go"