diff --git a/docs/design-context-categorization/CONTENTS-TABLE.html b/docs/design-context-categorization/CONTENTS-TABLE.html new file mode 100644 index 000000000..d96d9e422 --- /dev/null +++ b/docs/design-context-categorization/CONTENTS-TABLE.html @@ -0,0 +1,166 @@ + + + + +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 new file mode 100644 index 000000000..41d6ef2f0 --- /dev/null +++ b/docs/design-context-categorization/CONTENTS-TABLE.md @@ -0,0 +1,104 @@ +# 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 new file mode 100644 index 000000000..9ca76a6c8 --- /dev/null +++ b/docs/design-context-categorization/CONTENTS.md @@ -0,0 +1,200 @@ +# 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 new file mode 100644 index 000000000..40f46ea69 --- /dev/null +++ b/docs/design-context-categorization/MISSING.md @@ -0,0 +1,41 @@ +# 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 new file mode 100644 index 000000000..8a08e11db --- /dev/null +++ b/docs/design-context-categorization/ORPHANS.md @@ -0,0 +1,34 @@ +# 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/PROVENANCE.md b/docs/design-context-categorization/PROVENANCE.md new file mode 100644 index 000000000..a78fb6eb2 --- /dev/null +++ b/docs/design-context-categorization/PROVENANCE.md @@ -0,0 +1,76 @@ +# Provenance: Derived vs. Questionnaire-Answered Fields + +A requirement surfaced from the "Upgrading `/impeccable init`" landscape doc: the new visual document seed (chat asset/reference upload + local-browser slides for Color, Typography, Motion, Layout, Elevation, Iconography) must be **resettable**. A user can go back and redo one slide (e.g. Iconography) or the whole seed, without disturbing fields that came from somewhere else. + +Everything that isn't scanned off code is a **questionnaire answer** in the broad sense — nothing in `PRODUCT.md` or `DESIGN.md` is invented by the agent unprompted. But "questionnaire" isn't one thing: it happens through different commands and different UIs (chat vs. a local-browser slide). "Planned" vs. "already shipped" is a maturity detail on the specific field (called out in that field's `Value`/`Derived from` columns in [`CONTENTS-TABLE.md`](./CONTENTS-TABLE.md)), not a different provenance category — the new seed flow's chat portion is more of the same `init.md`/`document.md`-style chat interview, just under `document.md`; its browser portion is more of the same card-UI pattern the Layout-strictness slide already uses today. So provenance is four tags, not seven: + +- **Derived** — read directly off existing code (scanned CSS tokens, component classes). Changing it means re-scanning, not re-asking. +- **Questionnaire — In-chat (init)** — `PRODUCT.md` fields, asked in chat during `/impeccable init`'s Step 3. Today's mechanism for every non-Derived `PRODUCT.md` field (Users, Purpose, Positioning, Brand Personality, Anti-references, Conversion & proof, Design Principles, Accessibility). Free-form, not persisted for reset. +- **Questionnaire — In-chat (document)** — `DESIGN.md` fields asked in chat during `document.md`. Covers both today's qualitative round (North Star name, color role names/strategy, elevation/component feel, signature-component ideas) and the new seed flow's chat portion (asset/logo/moodboard upload, three named references, one named anti-reference, the image-gen capability check). Free-form, not persisted for reset — except where the new seed work adds persistence (see below). +- **Questionnaire — Browser (document)** — `DESIGN.md` fields asked through a visual card UI during `document.md`. Covers both today's shipped Layout-strictness slide (Simple grid / Balanced / Editorial / Freeform) and the new seed flow's browser slides (Color amount, Visual cues, Palette tokens, Typography, Motion, Layout, Elevation, Iconography). +- **Computed** — generated by the agent from other values (tonal ramps, breakpoints, HTML/CSS snippets). Never directly asked at all. + +The persisted/resettable mechanism below is in scope only for the **new, not-yet-shipped fields** within `Browser (document)` and `In-chat (document)` — i.e. the fields `CONTENTS-TABLE.md` marks `(planned)`. The fields already shipped under those same two tags (today's qualitative round, today's Layout-strictness slide) aren't persisted and stay that way unless retrofitted — see [`MISSING.md`](./MISSING.md) and open question #1 below. + +## Where it's stored + +In `design.json`, not inline in `DESIGN.md`. `DESIGN.md` stays a clean, human-readable artifact; `design.json` is already the structured sidecar other tooling reads (`colorMeta`, `typographyMeta`, `shadows`, `motion`, `breakpoints`, `components`, `narrative`), so provenance belongs next to it, not as HTML comments scattered through the markdown. + +## Proposed schema addition + +Two changes to `design.json`: + +**1. A `source` tag on existing per-field metadata**, so a value's provenance travels with it: + +```json +"extensions": { + "colorMeta": { + "dusty-plum": { + "role": "primary", + "source": "crawl" + } + }, + "typographyMeta": { + "display": { + "source": "questionnaire" + } + } +} +``` + +Values: `"crawl"`, `"chat-init"`, `"chat-document"`, `"browser-document"`, `"computed"`. A field's `(planned)` status (i.e. whether it's part of the new, not-yet-shipped seed work) is tracked by whether it has a `questionnaire.sections` entry at all, not by a separate source value — see the block below. + +**2. A top-level `questionnaire` block** — the actual answer log, keyed by slide/section, needed for reset at either granularity: + +```json +"questionnaire": { + "version": 1, + "lastRunAt": "2026-07-09T22:40:00.000Z", + "sections": { + "assets": { "status": "answered", "answeredAt": "...", "answers": { "logos": [], "referenceImages": [], "moodboards": [] }, "producedPaths": [] }, + "references": { "status": "answered", "answeredAt": "...", "answers": { "named": ["Kinfolk", "Cereal"] }, "producedPaths": ["narrative.overview"] }, + "antiReference": { "status": "answered", "answeredAt": "...", "answers": { "named": "Squarespace wedding-florist template" }, "producedPaths": ["narrative.donts"] }, + "color": { "status": "answered", "answeredAt": "...", "answers": { "amount": "restrained", "visualCue": "...", "paletteTokens": {"...": "..."} }, "producedPaths": ["extensions.colorMeta"] }, + "typography": { "status": "answered", "answeredAt": "...", "answers": { "fontPair": "Shippori Mincho / Source Sans 3", "typeDirection": "editorial" }, "producedPaths": ["extensions.typographyMeta"] }, + "motion": { "status": "answered", "answeredAt": "...", "answers": { "easing": "ease-standard", "duration": "150ms", "animationType": "crossfade" }, "producedPaths": ["extensions.motion"] }, + "layout": { "status": "answered", "answeredAt": "...", "answers": { "radii": "square", "spacingStrategy": "fluid", "boundaryStyle": "position/distance" }, "producedPaths": ["rounded", "spacing"] }, + "elevation": { "status": "answered", "answeredAt": "...", "answers": { "shadowSystem": "flat-by-doctrine" }, "producedPaths": ["extensions.shadows"] }, + "iconography": { "status": "answered", "answeredAt": "...", "answers": { "pack": "Lucide" }, "producedPaths": ["extensions.iconography"] } + } +} +``` + +`producedPaths` is what makes reset safe: it tells the reset routine exactly which `design.json`/`DESIGN.md` fields that section's answer wrote to, so redoing one slide only touches those paths and leaves everything else (crawl-derived or answered in a different slide) untouched. + +## Reset, both granularities + +- **Whole-flow reset**: clear all `questionnaire.sections`, re-run the seed from the assets/references chat step through every browser slide, same as a first-time seed. +- **Per-section reset**: user says "redo iconography" (or picks it from a menu). Agent reads `questionnaire.sections.iconography.answers` to show what was previously picked, lets the user redo just that slide, and overwrites only `producedPaths` for that section — no re-scan, no touching Color/Typography/etc. +- **Fields with `source: "crawl"`**: not resettable through this mechanism at all. Changing them means re-running `/impeccable document`'s scan (Step 1-2), or a manual code edit. The questionnaire reset flow should refuse to "reset" a crawl-derived field and say so. + +## Open questions + +1. **Scope**: this spec covers the new, not-yet-shipped fields within `In-chat (document)` and `Browser (document)` only. Should the fields already shipped under those same two tags (today's qualitative round, today's Layout-strictness slide), plus all of `In-chat (init)`, get the same persisted/resettable treatment eventually, so *all* of `PRODUCT.md`/`DESIGN.md` becomes resettable, not just the new seed's slice? That's a bigger lift — it touches `init.md`'s chat rounds too, and it would mean retrofitting a `questionnaire.sections` entry for flows that already shipped without one. +2. **Drift after manual edits**: if a user hand-edits a questionnaire-sourced value directly in `DESIGN.md` after the seed ran, does `source` flip to a fourth state (`"manual"`), or does the stale `questionnaire.sections` entry silently go out of sync with the doc? Needs a decision before reset ships, or resets could clobber a deliberate manual change. +3. **Existing repos with `design.json` but no `questionnaire` block** (every file generated before this ships): reset should degrade gracefully — treat missing `questionnaire` as "nothing resettable yet, only a fresh full seed is available" rather than erroring. +4. **`producedPaths` granularity**: paths above are section-level (e.g. `extensions.colorMeta`). If two slides ever write into the same object (unlikely given the current slide breakdown, but worth checking against the final slide list), path-level conflicts need a tie-break rule. diff --git a/docs/design-context-categorization/README.md b/docs/design-context-categorization/README.md new file mode 100644 index 000000000..4c60f073e --- /dev/null +++ b/docs/design-context-categorization/README.md @@ -0,0 +1,16 @@ +# Design Context Categorization + +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 + +- [`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.