From 6c2a79891c44e6d838213766f5f8d54ac685fa1c Mon Sep 17 00:00:00 2001 From: Abdul Wahab Date: Fri, 28 Aug 2026 01:06:56 +0500 Subject: [PATCH] Remove stale design-context-categorization docs PROVENANCE.md specs a design.json questionnaire/producedPaths schema that shipped nowhere and contradicts the store DESIGN-CONTEXT-ARCHITECTURE.md documents; design-context.html is an 89KB frozen prototype snapshot with no inbound references (the port to picker/ is complete, and git history keeps it); the README only indexed the two. Co-Authored-By: Claude Fable 5 --- .../PROVENANCE.md | 76 - docs/design-context-categorization/README.md | 10 - .../design-context.html | 2447 ----------------- 3 files changed, 2533 deletions(-) delete mode 100644 docs/design-context-categorization/PROVENANCE.md delete mode 100644 docs/design-context-categorization/README.md delete mode 100644 docs/design-context-categorization/design-context.html diff --git a/docs/design-context-categorization/PROVENANCE.md b/docs/design-context-categorization/PROVENANCE.md deleted file mode 100644 index 44b0377f6..000000000 --- a/docs/design-context-categorization/PROVENANCE.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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`, now in working notes), 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` (working notes) 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 deleted file mode 100644 index a5bb02439..000000000 --- a/docs/design-context-categorization/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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. - -## Documents - -- [`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/design-context.html b/docs/design-context-categorization/design-context.html deleted file mode 100644 index f2616ed71..000000000 --- a/docs/design-context-categorization/design-context.html +++ /dev/null @@ -1,2447 +0,0 @@ - - - - - -Design Context — Hanazono Atelier - - - - - - - - - - - - - - -
- - - Impeccable - - -
- - -
-
- -
-

Design context — Hanazono Atelier

- -
-
- - - - - - - - - - - - - - - - - - - -
-
-
- - - - - - - - - - - - - - - - - - - - - - - - -