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 for the mechanism and 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, 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, 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):

• 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):

• 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):

• 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):

• 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):

• 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"