version 0.2.0 replaces fromer version!

README.md

@@ -4,44 +4,109 @@ The neutral, mostly-black-and-white visual language for **whynot** — Tegwick's
 
 > A prototype is a question made tangible. — `whynot-control/INTENT.md`
 
-This repository is the **implementation surface**. The *language* of the system — voice, casing, motifs, the reasoning behind each rule — lives in this README. The *artefact* — the CSS, the components, the assets — lives in `src/` and `assets/`.
+This repository is the **implementation surface** for `whynot`'s visual language. It ships:
 
-If you're new here, read these in order:
+- **Tokens** (`tokens/*.json`) — source-of-truth colour, type, spacing values.
+- **CSS** (`src/styles/*.css`) — drop-in stylesheets for any HTML context.
+- **Web components** (`src/elements/*.js`) — Lit-based custom elements that work in React, Django, Vue, Svelte, plain HTML, anywhere.
+- **Adapters** (`adapters/django/`) — optional `{% include %}` partials for Django teams.
 
-1. **`DesignSystemIntroduction.md`** — how this repo relates to `whynot-control`, the Claude atelier, and consuming apps. Pipeline, versioning, propagation.
-2. **`SKILL.md`** — the Agent Skill manifest. Read this if you (or an agent) will be generating new artefacts in this style.
-3. **This README** — the full design language: tokens, components, content rules, iconography.
-4. **`CONTRIBUTING.md`** — how to propose, review, and ship a change.
+Framework-agnostic by design. Consumers do **not** re-implement components per framework — they use the same `<wn-button>` everywhere.
+
+## Read first
+
+| File | What's in it |
+|---|---|
+| `DesignSystemIntroduction.md` | How this repo relates to `whynot-control`, the Claude atelier, and consuming apps. Three-layer architecture, propagation pipeline, versioning, A1 staging. |
+| `MultiFrameworkSupport.md` | How to consume from React, Django, HTMX, Vue, plain HTML. Per-framework setup, SSR specifics, hydration story. |
+| `SKILL.md` | Agent Skill manifest, cross-compatible with Claude Code. Drop into `.claude/skills/` of any consuming repo. |
+| This README | Full design language: tokens, components, content rules, iconography. |
+| `CONTRIBUTING.md` | How to propose, review, and ship a change. |
+| `BOOTSTRAP.md` | First-push instructions for priming this repo. Delete after use. |
 
 ## Quick start
 
+### Plain HTML
+
+```html
+<link rel="stylesheet" href="/whynot/colors_and_type.css">
+<link rel="stylesheet" href="/whynot/components.css">
+<script type="module" src="/whynot/index.js"></script>
+
+<wn-button variant="primary">Promote prototype</wn-button>
+```
+
+### Node-tooled consumer (React, Vite, Next, Vue, …)
+
 ```sh
-# in a consuming repo
-pnpm add git+ssh://git@gitea.example.com/whynot/whynot-design.git#v0.1.0
+pnpm add git+ssh://git@gitea.example.com/whynot/whynot-design.git#v0.2.0
+```
+
+```js
+// once, at app root
+import "@whynot/design/styles/colors_and_type.css";
+import "@whynot/design/styles/components.css";
+import "@whynot/design";
 ```
 
 ```jsx
-// at the app root, once
-import "@whynot/design/styles/colors_and_type.css";
-
-// anywhere
-import { Button, Tag, Eyebrow, StageDot } from "@whynot/design";
+<wn-button variant="primary">Promote prototype</wn-button>
+<wn-pipeline active-idx="3"></wn-pipeline>
 ```
 
+### Django
+
+```django
+{# templates/base.html #}
+{% include "whynot/_base_head.html" %}
+
+{# any template #}
+<wn-page-header eyebrow="whynot · prototypes" title="Prototypes"></wn-page-header>
+<wn-prototype-card card-id="{{ p.id }}" signal="{{ p.signal }}">
+  <span slot="pitch">{{ p.pitch }}</span>
+</wn-prototype-card>
+```
+
+See `MultiFrameworkSupport.md` for the full integration story per framework.
+
 ## What lives where
 
-| Path | Contents |
-|---|---|
-| `tokens/` | Source-of-truth design tokens as JSON. |
-| `src/styles/colors_and_type.css` | All CSS variables + semantic element styles. The single file every consumer imports. |
-| `src/components/` | React components (JSX, no build step). |
-| `src/index.js` | Barrel export. |
-| `assets/` | Logo, mark, future imagery. |
-| `examples/whynot-control/` | Live click-through UI kit. Also the Playwright visual-regression target. |
+```
+whynot-design/
+├── tokens/                           Source-of-truth design tokens (JSON).
+├── src/
+│   ├── styles/
+│   │   ├── colors_and_type.css       Layer 1 — tokens + semantic element styles.
+│   │   └── components.css            Layer 1 — utility classes for every component.
+│   ├── elements/                     Layer 2 — Lit web components.
+│   │   ├── atoms.js                  wn-button, wn-tag, wn-eyebrow, wn-stamp,
+│   │   │                             wn-stage-dot, wn-phase-dot, wn-icon
+│   │   ├── form.js                   wn-input, wn-textarea, wn-select,
+│   │   │                             wn-search-input, wn-field-row
+│   │   ├── layout.js                 wn-card, wn-modal, wn-table, wn-banner,
+│   │   │                             wn-toast, wn-empty-state, wn-breadcrumb
+│   │   ├── chrome.js                 wn-top-nav, wn-sidebar, wn-page-header,
+│   │   │                             wn-pipeline, wn-prototype-card
+│   │   └── icons.js                  Lucide-derived icon paths.
+│   └── index.js                      Side-effect import — registers all elements.
+├── adapters/django/                  Layer 3 — optional Django partials.
+├── examples/
+│   ├── showcase/index.html           Every component on one page. Playwright target.
+│   └── whynot-control/index.html     Full app composition (React + custom elements).
+└── assets/                           Logo, mark.
+```
+
+## Open this locally
+
+```sh
+pnpm install
+pnpm showcase        # then visit http://localhost:4321/examples/showcase/
+pnpm example         # then visit http://localhost:4322  (whynot-control kit)
+```
 
 ---
 
-> The remainder of this README is the full design language — colour reasoning, type stack, content rules, iconography. It is identical to the language defined in the Claude atelier project and should stay in sync. Treat it as authoritative.
+> The remainder of this README is the full design language — colour reasoning, type stack, content rules, iconography. Treat it as authoritative.
 
 
 ## CONTENT FUNDAMENTALS