From 3202a3aab5a09a5ed3d3482fa50e42ab34186a53 Mon Sep 17 00:00:00 2001 From: Abdul Wahab Date: Thu, 20 Aug 2026 07:28:56 +0500 Subject: [PATCH] Trim design-context-categorization docs to prototype, provenance, and index Co-authored-by: Cursor --- .../CONTENTS-TABLE.html | 166 -------------- .../CONTENTS-TABLE.md | 104 --------- .../design-context-categorization/CONTENTS.md | 200 ---------------- docs/design-context-categorization/MISSING.md | 41 ---- docs/design-context-categorization/ORPHANS.md | 34 --- docs/design-context-categorization/README.md | 15 +- docs/design-context-categorization/WHAT.md | 216 ------------------ 7 files changed, 4 insertions(+), 772 deletions(-) delete mode 100644 docs/design-context-categorization/CONTENTS-TABLE.html delete mode 100644 docs/design-context-categorization/CONTENTS-TABLE.md delete mode 100644 docs/design-context-categorization/CONTENTS.md delete mode 100644 docs/design-context-categorization/MISSING.md delete mode 100644 docs/design-context-categorization/ORPHANS.md delete mode 100644 docs/design-context-categorization/WHAT.md diff --git a/docs/design-context-categorization/CONTENTS-TABLE.html b/docs/design-context-categorization/CONTENTS-TABLE.html deleted file mode 100644 index d96d9e422..000000000 --- a/docs/design-context-categorization/CONTENTS-TABLE.html +++ /dev/null @@ -1,166 +0,0 @@ - - - - -Contents Table - - - - -

Contents Table

- -

Source legend

- -

See PROVENANCE.md for the full mechanism. Where a value can come from either scan mode or the planned seed flow, both are listed.

- - - - - - - - - - - - -
SourceMeaning
DerivedScanned off existing code. Changed only by re-scanning, not by re-answering a question.
Questionnaire — In-chat (init)PRODUCT.md fields, asked in chat during /impeccable init Step 3. Not persisted or resettable.
Questionnaire — In-chat (document)DESIGN.md fields asked in chat during document.md — covers both today's qualitative round and the new seed flow's chat portion (assets, named references, anti-reference). Not persisted or resettable today; the (planned) rows are where that's changing.
Questionnaire — Browser (document)DESIGN.md fields asked through a visual card UI during document.md — covers both today's shipped Layout-strictness slide and the new seed flow's browser slides (Color, Typography, Motion, Layout, Elevation, Iconography). Same persistence note as above — see PROVENANCE.md.
ComputedGenerated by the agent from other values. Never directly asked.
- -

Categories

- - - -

Audience

- - - - - - - - - - - -
ValueDerived fromSource
Primary/secondary user rolePRODUCT.md · UsersQuestionnaire — In-chat (init)
Confirmed primary/secondary splitPRODUCT.md · Users (PR #315)Questionnaire — In-chat (init)
Context, job-to-be-donePRODUCT.md · UsersQuestionnaire — In-chat (init)
Emotional goal on landingPRODUCT.md · Brand PersonalityQuestionnaire — In-chat (init)
- -

Product

- - - - - - - - - - - - - - -
ValueDerived fromSource
NameDESIGN.md frontmatter nameDerived
Register (brand/product)PRODUCT.md · RegisterQuestionnaire — In-chat (init)
What it does, success definitionPRODUCT.md · Product PurposeQuestionnaire — In-chat (init)
Use cases (implicit)PRODUCT.md · Product PurposeDerived
Differentiator / strategic claimPRODUCT.md · Positioning (PR #315)Questionnaire — In-chat (init)
CTAs, memorable line, belief ladderPRODUCT.md · Conversion & proof (PR #315, brand only)Questionnaire — In-chat (init)
Proof assets (testimonials, press, logos)PRODUCT.md · Conversion & proof (PR #315, brand only)Questionnaire — In-chat (init)
- -

Brand

- - - - - - - - - - - - -
ValueDerived fromSource
Identity name + narrative (long form)DESIGN.md · OverviewQuestionnaire — In-chat (document)
Description (short form of the same narrative)DESIGN.md frontmatter descriptionQuestionnaire — In-chat (document)
Three words, voice, tone, referencesPRODUCT.md · Brand PersonalityQuestionnaire — In-chat (init)
Anti-referencesPRODUCT.md · Anti-referencesQuestionnaire — In-chat (init)
Strategic principlesPRODUCT.md · Design PrinciplesQuestionnaire — In-chat (init)
- -

Color

- - - - - - - - - - - - -
ValueDerived fromSource
Palette (hex)DESIGN.md frontmatter colorsDerived / Questionnaire — Browser (document)
Roles (primary/neutral)DESIGN.md · ColorsQuestionnaire — In-chat (document)
Strategy (named rules)DESIGN.md · Colors → Named RulesQuestionnaire — In-chat (document)
Tints (opacity variants)DESIGN.md frontmatter colorsDerived / Questionnaire — Browser (document)
Tonal ramps (OKLCH)design.json · colorMeta.tonalRampComputed
- -

Typography

- - - - - - - - - - - -
ValueDerived fromSource
Font familiesDESIGN.md frontmatter typographyDerived / Questionnaire — Browser (document)
Typescale (base + ratio, e.g. Major Third)Visual document seed (planned)Questionnaire — Browser (document)
Hierarchy (role/size/weight/etc.)DESIGN.md · HierarchyDerived
Readability rulesDESIGN.md · Named RulesComputed
- -

Iconography

- - - - - - - - -
ValueDerived fromSource
Icon library/style (Lucide/Tabler Icons/Hugeicons)Visual document seed (planned)Questionnaire — Browser (document)
- -

Material

- - - - - - - - - - - - - - - - -
ValueDerived fromSource
Spacing / layout scaleDESIGN.md frontmatter spacingDerived / Questionnaire — Browser (document)
Layout structure / grid strictnessVisual document seed (existing)Questionnaire — Browser (document)
Breakpointsdesign.json · extensions.breakpointsComputed
RadiusDESIGN.md frontmatter roundedDerived / Questionnaire — Browser (document)
BordersDESIGN.md prose (Elevation/Colors)Derived
SurfacesDESIGN.md · Colors → NeutralDerived
Shadows + elevationDESIGN.md · Elevation; design.json · shadowsDerived / Questionnaire — Browser (document)
Motion feel (qualitative)DESIGN.md · Do's and Don'tsQuestionnaire — In-chat (document) / Questionnaire — Browser (document)
Motion tokens (ease/duration)design.json · extensions.motionComputed / Questionnaire — Browser (document)
- -

Interface

- - - - - - - - - - - - -
ValueDerived fromSource
Component tokensDESIGN.md frontmatter componentsDerived
Component prose + statesDESIGN.md · ComponentsDerived / Questionnaire — In-chat (document)
Signature/future componentsDESIGN.md · ComponentsQuestionnaire — In-chat (document)
Concrete HTML/CSS snippetsdesign.json · components[]Computed
Accessibility & InclusionPRODUCT.md · Accessibility & InclusionQuestionnaire — In-chat (init)
- - - diff --git a/docs/design-context-categorization/CONTENTS-TABLE.md b/docs/design-context-categorization/CONTENTS-TABLE.md deleted file mode 100644 index 41d6ef2f0..000000000 --- a/docs/design-context-categorization/CONTENTS-TABLE.md +++ /dev/null @@ -1,104 +0,0 @@ -# Contents Table - -## Source legend - -See [`PROVENANCE.md`](./PROVENANCE.md) for the full mechanism. Where a value can come from either scan mode or the planned seed flow, both are listed. - -| Source | Meaning | -| --- | --- | -| Derived | Scanned off existing code. Changed only by re-scanning, not by re-answering a question. | -| Questionnaire — In-chat (init) | `PRODUCT.md` fields, asked in chat during `/impeccable init` Step 3. Not persisted or resettable. | -| Questionnaire — In-chat (document) | `DESIGN.md` fields asked in chat during `document.md` — covers both today's qualitative round and the new seed flow's chat portion (assets, named references, anti-reference). Not persisted or resettable today; the `(planned)` rows are where that's changing. | -| Questionnaire — Browser (document) | `DESIGN.md` fields asked through a visual card UI during `document.md` — covers both today's shipped Layout-strictness slide and the new seed flow's browser slides (Color, Typography, Motion, Layout, Elevation, Iconography). Same persistence note as above — see `PROVENANCE.md`. | -| Computed | Generated by the agent from other values. Never directly asked. | - -## Categories - -- Audience -- Product -- Brand -- Color -- Typography -- Iconography -- Material -- Interface - -## Audience - -| Value | Derived from | Source | -| --- | --- | --- | -| Primary/secondary user role | `PRODUCT.md` · Users | Questionnaire — In-chat (init) | -| Confirmed primary/secondary split | `PRODUCT.md` · Users (PR #315) | Questionnaire — In-chat (init) | -| Context, job-to-be-done | `PRODUCT.md` · Users | Questionnaire — In-chat (init) | -| Emotional goal on landing | `PRODUCT.md` · Brand Personality | Questionnaire — In-chat (init) | - -## Product - -| Value | Derived from | Source | -| --- | --- | --- | -| Name | `DESIGN.md` frontmatter `name` | Derived | -| Register (`brand`/`product`) | `PRODUCT.md` · Register | Questionnaire — In-chat (init) | -| What it does, success definition | `PRODUCT.md` · Product Purpose | Questionnaire — In-chat (init) | -| Use cases (implicit) | `PRODUCT.md` · Product Purpose | Derived | -| Differentiator / strategic claim | `PRODUCT.md` · Positioning (PR #315) | Questionnaire — In-chat (init) | -| CTAs, memorable line, belief ladder | `PRODUCT.md` · Conversion & proof (PR #315, brand only) | Questionnaire — In-chat (init) | -| Proof assets (testimonials, press, logos) | `PRODUCT.md` · Conversion & proof (PR #315, brand only) | Questionnaire — In-chat (init) | - -## Brand - -| Value | Derived from | Source | -| --- | --- | --- | -| Identity name + narrative (long form) | `DESIGN.md` · Overview | Questionnaire — In-chat (document) | -| Description (short form of the same narrative) | `DESIGN.md` frontmatter `description` | Questionnaire — In-chat (document) | -| Three words, voice, tone, references | `PRODUCT.md` · Brand Personality | Questionnaire — In-chat (init) | -| Anti-references | `PRODUCT.md` · Anti-references | Questionnaire — In-chat (init) | -| Strategic principles | `PRODUCT.md` · Design Principles | Questionnaire — In-chat (init) | - -## Color - -| Value | Derived from | Source | -| --- | --- | --- | -| Palette (hex) | `DESIGN.md` frontmatter `colors` | Derived / Questionnaire — Browser (document) | -| Roles (primary/neutral) | `DESIGN.md` · Colors | Questionnaire — In-chat (document) | -| Strategy (named rules) | `DESIGN.md` · Colors → Named Rules | Questionnaire — In-chat (document) | -| Tints (opacity variants) | `DESIGN.md` frontmatter `colors` | Derived / Questionnaire — Browser (document) | -| Tonal ramps (OKLCH) | `design.json` · `colorMeta.tonalRamp` | Computed | - -## Typography - -| Value | Derived from | Source | -| --- | --- | --- | -| Font families | `DESIGN.md` frontmatter `typography` | Derived / Questionnaire — Browser (document) | -| Typescale (base + ratio, e.g. Major Third) | Visual document seed (planned) | Questionnaire — Browser (document) | -| Hierarchy (role/size/weight/etc.) | `DESIGN.md` · Hierarchy | Derived | -| Readability rules | `DESIGN.md` · Named Rules | Computed | - -## Iconography - -| Value | Derived from | Source | -| --- | --- | --- | -| Icon library/style (Lucide/Tabler Icons/Hugeicons) | Visual document seed (planned) | Questionnaire — Browser (document) | - -## Material - -| Value | Derived from | Source | -| --- | --- | --- | -| Spacing / layout scale | `DESIGN.md` frontmatter `spacing` | Derived / Questionnaire — Browser (document) | -| Layout structure / grid strictness | Visual document seed (existing) | Questionnaire — Browser (document) | -| Breakpoints | `design.json` · `extensions.breakpoints` | Computed | -| Radius | `DESIGN.md` frontmatter `rounded` | Derived / Questionnaire — Browser (document) | -| Borders | `DESIGN.md` prose (Elevation/Colors) | Derived | -| Surfaces | `DESIGN.md` · Colors → Neutral | Derived | -| Shadows + elevation | `DESIGN.md` · Elevation; `design.json` · `shadows` | Derived / Questionnaire — Browser (document) | -| Motion feel (qualitative) | `DESIGN.md` · Do's and Don'ts | Questionnaire — In-chat (document) / Questionnaire — Browser (document) | -| Motion tokens (ease/duration) | `design.json` · `extensions.motion` | Computed / Questionnaire — Browser (document) | - -## Interface - -| Value | Derived from | Source | -| --- | --- | --- | -| Component tokens | `DESIGN.md` frontmatter `components` | Derived | -| Component prose + states | `DESIGN.md` · Components | Derived / Questionnaire — In-chat (document) | -| Signature/future components | `DESIGN.md` · Components | Questionnaire — In-chat (document) | -| Concrete HTML/CSS snippets | `design.json` · `components[]` | Computed | -| Accessibility & Inclusion | `PRODUCT.md` · Accessibility & Inclusion | Questionnaire — In-chat (init) | diff --git a/docs/design-context-categorization/CONTENTS.md b/docs/design-context-categorization/CONTENTS.md deleted file mode 100644 index 9ca76a6c8..000000000 --- a/docs/design-context-categorization/CONTENTS.md +++ /dev/null @@ -1,200 +0,0 @@ -# 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" diff --git a/docs/design-context-categorization/MISSING.md b/docs/design-context-categorization/MISSING.md deleted file mode 100644 index 40f46ea69..000000000 --- a/docs/design-context-categorization/MISSING.md +++ /dev/null @@ -1,41 +0,0 @@ -# What's Missing - -Genuine content gaps not produced by either example run (`noren-ops-20260708-1832`, `hanazono-atelier-20260708-1832`), regardless of category. - -## Resolved by PR #315 - -[pbakaus/impeccable#315](https://github.com/pbakaus/impeccable/pull/315) ("Expand init to capture positioning, conversion, and proof context") adds two new `PRODUCT.md` sections to the Step 3 interview in `skill/reference/init.md`: - -- `## Positioning` (both registers) — "the single strategic claim every screen reinforces" -- `## Conversion & proof` (brand register only; product register omits the section entirely) — primary/secondary CTA, the line a visitor remembers after 10 seconds, belief ladder, and "Proof on hand" (testimonials, case studies, press, client/partner logos — referenced by path, collected under `.impeccable/assets/proof/`) - -What that resolves: - -- ~~A labeled differentiator field~~ → `## Positioning` is exactly this, now asked explicitly instead of living buried inside Design Principles. -- ~~Proof points as actual content~~ → `## Conversion & proof` → "Proof on hand" collects real testimonials/case studies/press/logos by path, not just the proof-quote UI container. -- ~~A "what must be clear first" content-priority statement~~ → covered by the memorable-line + belief-ladder pair for brand register, and the pre-existing "primary workflow / primary task on any screen" question for product register. -- Explicit trust-trigger content for Audience → the *content* now exists (proof assets), but it's captured under Product (`Conversion & proof`), not Audience. See the note in [`ORPHANS.md`](./ORPHANS.md) — this isn't a new orphan, just a reminder that trust-trigger content lives one category over from where "Audience" would intuitively look for it. - -Also tightened (not a new field, but changes what's captured): `## Users` now requires an explicit, confirmed primary/secondary audience split — no manufactured splits, and a direct question when the surface's audience differs from who actually uses the product. - -## Partially resolved by the upcoming visual document seed - -Planned feature (not yet a PR): a new visual, card-based document seed adds three question areas — Typescale, Layout structure, and Iconography. Layout structure already exists in today's seed ("How strict should the layout feel?" — Simple grid / Balanced / Editorial / Freeform); Typescale and Iconography are new. - -- ~~Iconography, full stop~~ → **partially resolved.** The new "Which icon style should the design use?" question captures icon library/style (Lucide / Tabler Icons / Hugeicons). Icon style itself is no longer a total gap, but stroke weight, metaphor rules, icon-button behavior, and allowed/forbidden icon types are not part of this question and remain open — library choice implies a default aesthetic, not a full spec. -- Typography's font scale goes from hand-picked sizes to a named, generative rule: a base size + ratio (modular scale, e.g. Major Third) that derives the hierarchy, rather than each role's size being picked independently. Not something `MISSING.md` had called out explicitly before, but it's a real upgrade to how "font scale" gets captured. -- Layout structure (grid strictness) adds a rhythm/composition rule to Material that neither example run's `DESIGN.md` states explicitly today — closest existing analogue is the spacing scale, but "how strict is the grid" is a distinct decision from "what are the spacing values." - -## Not missing, but not resettable either - -Everything answered today gets baked directly into prose with no persisted record of the original question/answer pair: `Questionnaire — In-chat (init)` (nearly everything in `PRODUCT.md`), `Questionnaire — In-chat (document)`'s shipped fields (`DESIGN.md`'s North Star/color narrative/elevation feel), and `Questionnaire — Browser (document)`'s shipped fields (today's Layout-strictness card UI). There's nothing to reset any of them *to* — a user who wants to redo just the brand personality answer, or just the layout-strictness pick, has to manually edit the doc, not reopen a slide. Only the new fields being added to `In-chat (document)` and `Browser (document)` by the upcoming seed work are getting the persisted/resettable treatment. See [`PROVENANCE.md`](./PROVENANCE.md) open question #1 for whether the already-shipped fields should eventually get it too. - -## Still missing - -Untouched by PR #315 and the upcoming visual document seed: - -- Stroke weight, metaphor rules, icon-button behavior, and allowed/forbidden icon types within Iconography (library/style choice alone doesn't cover these) -- Dark-mode palette / inference logic -- Wordmark / logo fallback rule -- Texture/grain and folds/edges material language (or an explicit "none, by doctrine" statement) -- Conversion & proof content for product-register projects — the section is explicitly omitted there, so proof-point/trust-trigger content stays absent for product-register work (arguably correct scope for an internal app, but worth a second look if a given product-register project does have testimonials or logos worth capturing) diff --git a/docs/design-context-categorization/ORPHANS.md b/docs/design-context-categorization/ORPHANS.md deleted file mode 100644 index 8a08e11db..000000000 --- a/docs/design-context-categorization/ORPHANS.md +++ /dev/null @@ -1,34 +0,0 @@ -# Doesn't Have a Clean Place in the 8-Category Schema (Orphans) - -Present in current output, but no obvious bucket among Audience / Product / Brand / Color / Typography / Iconography / Material / Interface. - -## Resolved - -- **Register** (`product`/`brand`) → **Product**. It's the metadata switch that determines everything downstream, but downstream of what if not the product's own framing — it belongs next to Product Purpose. -- **Name** (`DESIGN.md` frontmatter `name`) → **Product**. The literal project name — an identifier, not a design decision; travels with Product Purpose rather than standing alone. (Originally bundled with `description` as "header metadata," but `description` isn't metadata — see next entry.) -- **Description** (`DESIGN.md` frontmatter `description`, e.g. "Calm HR ops workspace — dense tables, flat surfaces, dusty plum accent on warm cream.") → **Brand**, merged with Identity name + narrative. It's the same brand story as the `## 1. Overview` narrative, just compressed to one sentence — a short-form/long-form pair, not two separate facts. Filing it under Product next to `name` was a mistake carried over from treating the whole frontmatter block as one undifferentiated metadata unit. -- **Design Principles** (the numbered list as a unit) → **Brand**. Kept intact rather than decomposed per-bullet. Individual principles split close to 50/50 between voice/taste judgment calls (e.g. "Quiet authority over persuasion," "Restraint in every frame" — Brand) and product/workflow claims (e.g. "One workspace, not three spreadsheets" — Product), but the majority reads as brand cues and taste boundaries rather than product strategy, so the list stays with Brand instead of Product. -- **Spacing / layout scale** (`xs/sm/md/lg/xl/gutter/section` tokens) → **Material**. Treated as part of the physical construction of the interface alongside radius, borders, and elevation. -- **Breakpoints** (`sm/md/lg` px values) → **Material**. Responsive behavior of the same physical system: how surfaces reflow. -- **Accessibility & Inclusion** (WCAG target, reduced motion, alt text, color-vision pairing, plain-language/bilingual notes) → **Interface**. Per-item count across the two example runs: keyboard nav, screen-reader behavior, focus visibility, and alt text (Interface, the plurality) outweigh reduced motion (Material), contrast/color-vision pairing (Color), and bilingual/plain-language notes (Audience). Kept intact as a unit rather than split four ways, same treatment as Design Principles → Brand. -- **Tonal ramps** (`design.json` → `colorMeta.tonalRamp`, OKLCH 8-step scales per color) → **Color**. Promoted out of the sidecar into the human-readable doc, alongside the canonical hex — gives dark-mode inference raw material to work from instead of staying generated-only. -- **Motion tokens** (`design.json` → `extensions.motion`, e.g. `ease-standard`, `duration-fast`) → **Material**. Promoted out of the sidecar so the doc states the actual easing curve and duration behind "subtle lift on hover," not just the qualitative motion feel. - -## Checked against PR #315 — no new orphans - -[pbakaus/impeccable#315](https://github.com/pbakaus/impeccable/pull/315) adds `## Positioning` and `## Conversion & proof` to the `PRODUCT.md` template. Both map cleanly into the existing **Product** bucket, no new orphan: - -- `## Positioning` → **Product**, filling the differentiator sub-item. -- `## Conversion & proof` (CTAs, memorable line, belief ladder, proof assets) → **Product**, filling the proof-points and what's-must-be-clear-first sub-items. - -One nuance, not an orphan: the CTA/conversion-goal content doesn't exactly match any of the five sub-items in Product's current definition ("Purpose, differentiator, proof points, use cases, what must be clear first") — it's closest to Purpose but is more actionable/specific ("book a consultation" vs. "why this exists"). Worth a small wording update to Product's definition (e.g. adding "conversion goal") rather than a schema change. - -## Checked against the upcoming visual document seed (Typescale, Layout structure, Iconography) - -No new orphans. All three land inside categories that already exist in the schema: - -- **Typescale** (modular scale/ratio) → **Typography**, filling the font-scale sub-item with a generative rule instead of hand-picked sizes. -- **Layout structure** (grid strictness spectrum) → **Material**, alongside the already-resolved spacing/breakpoints orphans — same "physical construction of the interface" bucket. -- **Iconography** (icon library/style) → **Iconography** itself. This is the first content this category has ever had; it fills the "icon style" sub-item specifically, but stroke weight, metaphor rules, icon-button behavior, and forbidden types are outside this question's scope and stay open (tracked in [`MISSING.md`](./MISSING.md)). - -No open questions remain from this pass. diff --git a/docs/design-context-categorization/README.md b/docs/design-context-categorization/README.md index ecca008c6..a5bb02439 100644 --- a/docs/design-context-categorization/README.md +++ b/docs/design-context-categorization/README.md @@ -2,16 +2,9 @@ Analysis of what `/impeccable init` + `/impeccable document` currently produce (`PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`) against a proposed 8-category **design context doc**: Audience, Product, Brand, Color, Typography, Iconography, Material, Interface. -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` - ## Documents -- [`WHAT.md`](./WHAT.md) — first draft of what we're building: a visual, browsable rendering of this categorization on the live site. -- [`CONTENTS.md`](./CONTENTS.md) — what maps where, per category, with gaps and rationale. -- [`CONTENTS-TABLE.md`](./CONTENTS-TABLE.md) — the same mapping as lean per-category Value / Derived from / Source tables, no prose. -- [`MISSING.md`](./MISSING.md) — content gaps neither example run produces, regardless of category. -- [`ORPHANS.md`](./ORPHANS.md) — fields that exist today but don't have a clean home in the 8-category schema, plus open questions. -- [`PROVENANCE.md`](./PROVENANCE.md) — how the new visual document seed marks which fields are user-answered (resettable) vs. derived from code, and where that's stored. +- [`design-context.html`](./design-context.html): the standalone prototype the shipped `picker/scripts/design-context.js` and `picker/styles/design-context.css` were ported from. +- [`PROVENANCE.md`](./PROVENANCE.md): how the visual document seed marks which fields are user-answered (resettable) vs. derived from code, and where that's stored. + +The deeper analysis behind this set (category mapping, gaps, orphaned fields) lived in local working notes and is not tracked in this repo. diff --git a/docs/design-context-categorization/WHAT.md b/docs/design-context-categorization/WHAT.md deleted file mode 100644 index bc624d295..000000000 --- a/docs/design-context-categorization/WHAT.md +++ /dev/null @@ -1,216 +0,0 @@ -# What We're Building (First Draft) - -A visual, browsable rendering of the 8-category design context map — Audience, Product, Brand, Color, Typography, Iconography, Material, Interface — so a user can click through and see, category by category, what `/impeccable` already extracts from a project (and, later, what it's still missing). - -This is the **WHAT**, not the how: scope and shape, not component code. Two sources feed it, each responsible for a different half: - -- **Interaction mechanics** (the tile-grid landing, the click-to-fullscreen morph, hash routing, responsive collapse) come from the `Puppy Wear Design Context V2.html` prototype — see "Reference architecture" below. -- **Visual UI** (the "inside" — sidebar, content layout, typography, color, both light and dark) comes from the live [impeccable.style/docs/](https://impeccable.style/docs/) page, i.e. the actual local files that render it in this repo — see "Local reference" below. Content and category definitions come from [`CONTENTS-TABLE.md`](./CONTENTS-TABLE.md). - -Nothing here invents a third design language: the shape of the interaction is the prototype's, the skin is the live site's. - ---- - -## Reference architecture — interaction mechanics only - -Source: `Puppy Wear Design Context V2.html` (local prototype, not in this repo). What we take from it is behavior and geometry — how the tile grid is arranged, how a click turns into a fullscreen view, how that view is structured into regions and addressed by URL. The prototype's own CSS for what fills those regions (its sidebar/topbar/row styling, its color palette) is **not** carried over — that's replaced wholesale by the live site's actual components, described in "Visual language" below. - -- **Landing state** — an 8-tile asymmetric mosaic grid (an 18-column × 12-row grid with hand-placed spans per tile, matching the prototype's exact tile placement) with a circular center badge sitting on the seam between tiles. One tile per category — Audience, Product, Brand, Color, Typography, Iconography, Material, Interface — label only, no content, until opened. -- **Open transition** — clicking a tile creates a container positioned/sized to start exactly at the clicked tile's on-screen rect, then animates position/size/corner-radius to fullscreen, with the inner content fading/sliding in after a short delay. Closing runs the same transition in reverse, back to the originating tile's rect, then removes the element. (This is the prototype's `.expander` / `.expander.is-full` / `.expander.is-ready` mechanism — same tween, same timing, just filled with the live site's markup instead of the prototype's own.) -- **Detail shell regions** — once open, the view splits into: a **sidebar** (all 8 categories listed flat, in `CONTENTS-TABLE.md`'s order — Audience, Product, Brand, Color, Typography, Iconography, Material, Interface — active one highlighted, with jump-target sub-links for categories that have sub-content; no thematic clustering, unlike the prototype's own Context/Foundations/System grouping), a **topbar** (current category name + close control), and a **main pane** (that category's content, scrollable). What renders inside each region is the live site's, not the prototype's — see "Visual language." -- **Hash routing** — the open category is reflected in the URL (`#color`), so it's deep-linkable and back/forward-navigable via `popstate`. `Escape` and the close button both dismiss it. -- **Responsive fallback** (below ~920px) — the mosaic grid becomes a flex column, one tile per row in a fixed reading order (Product, Audience, Brand, Color, Typography, Iconography, Material, Interface); the sidebar collapses to a horizontal scroll strip. - ---- - -## Local reference — where impeccable.style/docs/ comes from - -[impeccable.style/docs/](https://impeccable.style/docs/) is not an external design to imitate from a screenshot — it's this repo, live. The exact files that render it: - -| What it renders | File | -| --- | --- | -| `/docs` landing page (start rail, command chooser, "Understand the system" list, full reference list) | [`site/pages/docs/index.astro`](../../site/pages/docs/index.astro) | -| `/docs/:slug` detail pages (one per command/reference topic — closest existing analog to a category detail view) | [`site/pages/docs/[...slug].astro`](../../site/pages/docs/%5B...slug%5D.astro) → [`site/layouts/Doc.astro`](../../site/layouts/Doc.astro) | -| Shared sidebar (grouped nav, one entry per item, `aria-current` for the active one) | [`site/components/DocsSidebar.astro`](../../site/components/DocsSidebar.astro) | -| Shared docs/sub-page layout shell (`.skills-layout`, `.skills-sidebar`, `.skills-main`, `.skills-detail`) | [`site/styles/sub-pages.css`](../../site/styles/sub-pages.css) | -| `/docs`-specific dark-lacquer skin + the `html.light` remap for this section | [`site/styles/docs-kinpaku.css`](../../site/styles/docs-kinpaku.css) | -| Sitewide brand tokens (colors, type) that everything above consumes | [`site/styles/kinpaku-tokens.css`](../../site/styles/kinpaku-tokens.css), [`site/styles/kinpaku-kit.css`](../../site/styles/kinpaku-kit.css) | -| Sitewide light-mode override layer | [`site/styles/light-mode.css`](../../site/styles/light-mode.css) | -| Theme toggle (auto/light/dark, `localStorage`-backed, sets `html.light`/`html.dark`) | [`site/scripts/utils/theme.js`](../../site/scripts/utils/theme.js), wired up in [`site/layouts/Base.astro`](../../site/layouts/Base.astro) (inline pre-paint script + `initThemeToggle()` call) | - -We build against these files directly, in both resolved themes (`html.light` and `html.dark`), not a one-off recreation of how the page happens to look in a screenshot. - ---- - -## UI sketch (ASCII) - -Proportions are illustrative, not to scale — the point is the asymmetry and the center badge, not exact grid math. Labels like "sidebar" and "topbar" below are generic region names; what actually renders inside them is `DocsSidebar` / `Doc.astro`'s header+prose pattern per "Visual language" above, not the prototype's own chrome. - -**Landing — 8-tile mosaic, nothing open:** - -``` -┌─────────────┬──────────────┬───────────────────┬─────────────┐ -│ │ │ │ │ -│ │ BRAND │ │ TYPOGRAPHY │ -│ │ │ AUDIENCE │ │ -│ PRODUCT ├──────┬───────┤ ├─────────────┤ -│ │ │ (●) │ │ │ -│ │ COLOR│ logo ├─────────────────────┤ MATERIAL │ -├─────────────┤ │ │ │ │ -│ ICONOGRAPHY │ │ │ INTERFACE │ │ -└─────────────┴──────┴───────┴─────────────────────┴─────────────┘ -``` - -**A tile mid-click, morphing toward fullscreen (FLIP animation):** - -``` -┌──────┬──────┬──────┐ ┌──────┬──────┬──────┐ ┌───────────────────────┐ -│ P │ B │ A │ │ P │▓▓▓▓▓▓│ A │ │ │ -├──────┼──────┼──────┤ → ├──────┼▓▓▓▓▓▓┼──────┤ → │ Color (open) │ -│ Ic │ [C]★ │ In │ │ Ic │▓▓▓▓▓▓│ In │ │ │ -└──────┴──────┴──────┘ └──────┴──────┴──────┘ └───────────────────────┘ - ★ user clicks "Color" same element grows in place sidebar + content - (top/left/width/height tween) fade in ~260ms later -``` - -**Expanded — sidebar + topbar + main, "Color" open:** - -``` -┌───────────────┬─────────────────────────────────────────────────────────┐ -│ Impeccable │ Color ✕ │ -├───────────────┼─────────────────────────────────────────────────────────┤ -│ · Audience │ Color │ -│ · Product │ Palette, roles, tints, strategy, tonal ramps. │ -│ · Brand │ │ -│ ► Color │ ┌────────────────────────────────────────────────────┐ │ -│ ↳ Palette │ │ ░░░░ ▒▒▒▒ ▓▓▓▓ ████ ▓▓▓▓ ▒▒▒▒ │ │ -│ · Typography │ │ (swatch fan — hover fans out, click copies) │ │ -│ · Iconography│ └────────────────────────────────────────────────────┘ │ -│ · Material │ │ -│ · Interface │ ───────────────────────────────────────────────────── │ -│ │ Palette (hex) DESIGN.md · colors Derived │ -│ │ ───────────────────────────────────────────────────── │ -│ │ Roles DESIGN.md · Colors In-chat │ -│ │ ───────────────────────────────────────────────────── │ -│ │ Strategy Colors → Named Rules In-chat │ -│ │ ───────────────────────────────────────────────────── │ -│ │ Tints colors (opacity) Derived │ -│ │ ───────────────────────────────────────────────────── │ -│ │ Tonal ramps (OKLCH) colorMeta.tonalRamp Computed │ -└───────────────┴─────────────────────────────────────────────────────────┘ -``` - -The sidebar is flat, in `CONTENTS-TABLE.md`'s own category order — no thematic clustering like the prototype's Context/Foundations/System groups. Decided; see "Decisions" at the end. - -**Responsive (< ~920px) — grid stacks, sidebar becomes a scroll strip:** - -``` -┌─────────────────────────┐ ┌──────────────────────────────────┐ -│ PRODUCT │ │[Product][Audience][Brand][►Color]│ -├─────────────────────────┤ │ ...horizontal scroll... →│ -│ AUDIENCE │ ├──────────────────────────────────┤ -├─────────────────────────┤ │ Color ✕ │ -│ BRAND │ │ │ -├─────────────────────────┤ │ ░░░ ▒▒▒ ▓▓▓ ███ ▓▓▓ ▒▒▒ │ -│ COLOR │ tap → │ │ -├─────────────────────────┤ │ Palette (hex) ... Derived │ -│ TYPOGRAPHY │ │ Roles ... In-chat │ -├─────────────────────────┤ │ Strategy ... In-chat │ -│ ICONOGRAPHY │ │ ... │ -├─────────────────────────┤ │ │ -│ MATERIAL │ │ │ -├─────────────────────────┤ │ │ -│ INTERFACE │ │ │ -└─────────────────────────┘ └──────────────────────────────────┘ -``` - ---- - -## UX flow (ASCII) - -``` - ┌─────────────────────────┐ - ┌───────►│ LANDING │ - │ │ 8-tile mosaic grid, │ - │ │ nothing open │ - │ └────────────┬────────────┘ - │ │ click a tile - │ │ (or page load with #hash) - │ ▼ - │ ┌─────────────────────────┐ - │ │ OPEN TRANSITION │ - │ │ tile rect → fullscreen │ - │ │ (FLIP morph, ~500ms) │ - │ └────────────┬────────────┘ - │ │ morph completes - │ ▼ - │ ┌─────────────────────────┐ - │ ┌───►│ EXPANDED │◄───┐ - │ │ │ sidebar + topbar + main │ │ - │ │ └────────────┬────────────┘ │ - │ │ │ │ - │ │ ┌───────────┼────────────┐ │ - │ │ ▼ ▼ ▼ │ - │ │ click a click a click a │ - │ │ different subnav swatch │ - │ │ category link → copy │ - │ │ in sidebar → scroll to hex, │ - │ │ that row "Copied!" │ - │ │ │ │ │ │ - │ │ └───────────┴────────────┘ │ - │ │ re-render main, update hash, │ - │ └───────────── no re-morph ─────────────┘ - │ │ - │ │ Escape, or click ✕ - │ ▼ - │ ┌─────────────────────────┐ - │ │ CLOSE TRANSITION │ - └────────┤ fullscreen → tile rect │ - │ (reverse morph) │ - └─────────────────────────┘ -``` - -Two entry points worth calling out: a direct tile click always starts from the tile's own rect (so the morph has somewhere real to animate from), while a page load with a `#category` hash in the URL skips straight to `EXPANDED` — the prototype does this via a short `setTimeout` rather than an instant snap, so the shell still feels like it "arrived" rather than being static markup. - ---- - -## Visual language — the inside (and the mosaic's skin) is impeccable.style/docs/, not the prototype - -The prototype supplies geometry and motion (previous section). Everything you'd actually call "the design" — color, type, borders, the sidebar, how a list of facts is laid out — comes from the live `/docs` implementation listed above, applied in both the regions the prototype defines (mosaic tiles, sidebar, topbar, main pane) and rendered correctly in both themes. - -- **Mosaic tiles (landing)** — keep the prototype's asymmetric grid *placement* (which tile sits where, the center badge), but the tile surface itself — border, corner radius, hover/focus treatment, background — pulls from the same surface tokens the rest of the site already uses for card-like elements (`--docs-panel-bg`, `--docs-row-bg`, `--docs-row-hover-bg`, `--docs-accent` from `docs-kinpaku.css`), so a tile reads as a natural extension of the site's existing surfaces, not the prototype's flat white/black `oklch(0% 0 0)` outline treatment. Tile label typography uses the site's existing display font (whatever `docs-kinpaku.css` / `kinpaku-tokens.css` already sets for large display text), not the prototype's Alumni Sans Pinstripe. -- **Sidebar (inside)** — structurally and visually **`DocsSidebar.astro`**: the `skills-sidebar` / `skills-sidebar-label` / `skills-sidebar-list` / `aria-current` pattern, applied as a single flat `skills-sidebar-list` of all 8 categories in `CONTENTS-TABLE.md`'s own order (Audience, Product, Brand, Color, Typography, Iconography, Material, Interface) — no `skills-sidebar-group` clustering, since there's no thematic grouping to apply. Not the prototype's own `docs-sidebar` / `docs-nav-link` / `docs-subnav` CSS, nor its Context/Foundations/System clusters — those are discarded entirely; only the per-category jump-target sub-links survive as `docs-subnav`-equivalent behavior under the active entry. -- **Topbar + main pane (inside)** — structurally and visually **`Doc.astro`**'s `.skills-main` / `.skills-detail` pattern: a header (`.sub-page-header` → `.sub-page-title` + `.sub-page-lede`) playing the role of the prototype's topbar-plus-title, followed by a content body (`.skills-detail-body.docs-body.prose`) playing the role of the main pane. Each category's Value / Derived-from / Source rows render as the same label-plus-secondary-line row shape the live `/docs` index already uses for its "Full command reference" list (primary text + a muted description line), not the prototype's bordered `.detail-row` two-column table look. -- **Color's swatch fan / Typography's type sample / Material's line diagram** — these three specialized blocks have no equivalent on the live site (nothing there needs a color-swatch strip), so they're the one place the prototype's own markup and interaction *do* carry over structurally — but skinned with the site's color tokens, not the prototype's `--care-glow` / `--paw-proof` custom palette. -- **Theme** — driven entirely by the existing toggle (`theme.js`, `html.light` / `html.dark`, wired in `Base.astro`). Both themes are first-class from the start because we're building against `docs-kinpaku.css`'s existing dark/light rule pairs, not authoring a new palette that then needs a light variant invented after the fact. -- **Motion** — the tile→fullscreen morph timing/easing and the responsive breakpoint stay as defined in "Reference architecture"; none of that is affected by this section. - ---- - -## Content model - -Source of truth: [`CONTENTS-TABLE.md`](./CONTENTS-TABLE.md). - -- **Legend** (5 source types: Derived, Questionnaire — In-chat (init), Questionnaire — In-chat (document), Questionnaire — Browser (document), Computed) — surfaced once, not per category (a persistent key, e.g. a footnote strip or an info toggle in the topbar). -- **8 categories**, each a list of rows: Value / Derived from / Source. Row counts vary today from 1 (Iconography) to 10 (Material). -- To avoid a second hand-maintained copy of the same data, the first build pass should read `CONTENTS-TABLE.md` directly (parsed into a small structured module at build time) rather than re-typing rows into markup. This doc stays the single source; the page is a renderer, not a fork. - ---- - -## Explicitly out of scope for this first draft - -- No live wiring to a real project's `PRODUCT.md` / `DESIGN.md` — this renders the fixed categorization, not a per-user report. -- No authoring/editing UI — read-only browse experience. -- Color's swatch-fan block (`.panel-colors`) carries over structurally, but `CONTENTS-TABLE.md` describes color *concepts* ("Palette (hex)", "Tints") rather than literal hex values — so it renders with placeholder/illustrative swatches for this first draft, not real per-project colors. Click-to-copy still works, just copies placeholder values. -- No new visual theme, font, or motion language beyond what gets set up by the token swap above. - ---- - -## Decisions - -1. **Sidebar grouping — flat, `CONTENTS-TABLE.md` order.** No thematic clusters (the prototype's Context/Foundations/System is dropped). All 8 categories sit at one level, in the exact order `CONTENTS-TABLE.md`'s own "Categories" list uses: Audience, Product, Brand, Color, Typography, Iconography, Material, Interface. -2. **Verification pass — confirmed.** Once built, screenshot-compare against the real `/docs` and `/docs/:slug` pages in both `html.light` and `html.dark`, same as any other `docs-kinpaku.css`-consuming page — not eyeballed once in whichever theme happens to be active during development. - -## Deferred - -- **Where this lives** (a page under `/docs`, e.g. filling the existing unused `Design Context` → `/docs/context` stub in `manualTopics` in [`site/pages/docs/index.astro`](../../site/pages/docs/index.astro), vs. its own standalone route) is not being decided as part of this draft. Revisit once the build is closer.