8000 feat(designmd): Stitch DESIGN.md dialect, project token discovery, live DOM snapshots, and active-DS guard by jangtrinh · Pull Request #457 · jangtrinh/design-os · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
"developerName": "DESIGN:OS",
"category": "Developer Tools",
"capabilities": [
"Interactive",
"Read",
"Write"
],
Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## 2026-11-17 - Stitch `DESIGN.md` dialect, project token discovery, live DOM snapshots, and active-DS prompt-plan guard

### Added
- **Dual-dialect `DESIGN.md` (`alpha` + `stitch` v1.0) in `ui designmd audit` and project scan**:
- `src/core/designmd-dialect.ts` and `src/core/designmd-audit-format.ts` auto-detect and validate both Google Labs' 8-section `alpha` dialect and Stitch's `stitch` dialect (`.stitch/DESIGN.md`, `version: "1.0"`, 6 numbered/unnumbered Stitch sections, and the 7-section classic flat-token layout).
- `src/core/designmd-audit-accessibility.ts` evaluates flat Material 3 `<role>` / `on-<role>` (and `inverse-<role>` / `inverse-on-<role>`) WCAG contrast pairs when nested `components:` tokens are omitted.
- `ui designmd audit <folder>` gains `--dialect auto|alpha|stitch`, falls back to `<folder>/.stitch/DESIGN.md` (and `.stitch/tokens.json`), includes `dialect` in `--json` output, and `scanProject` (`src/core/project-scan.ts`) detects `./.stitch/DESIGN.md`.
- **Multi-framework token source discovery & extended CSS color resolution in `ui designmd extract-tokens`**:
- `ui designmd extract-tokens --project <dir>` (`src/core/designmd-project-discovery.ts`) auto-discovers stylesheets and SFC `<style>` blocks across Next.js/React/Tailwind, shadcn/ui (`components.json`), Angular (`angular.json`), Vue/Nuxt (`nuxt.config.*`, `.vue`), SvelteKit (`src/app.css`, `.svelte`), and plain CSS/SCSS projects.
- `src/core/designmd-color-parse.ts` resolves `#rgb[a]`, `#rrggbb[aa]`, `rgb()`/`rgba()`, `hsl()`/`hsla()`, shadcn bare HSL channel triplets (`222.2 47.4% 11.2%`), and `oklch()` custom properties to `#rrggbb` `hex` values for `ui ingest-css-ds`.
- **Snapshot local asset inlining, dev-overlay cleanup, scroll unlock, and live `--render` CDP capture in `ui designmd snapshot`**:
- `src/core/designmd-html-snapshot.ts` strips dev overlays (`vite-error-overlay`, `nextjs-portal`, `webpack-dev-server-client-overlay`, `data-nextjs-dialog-overlay`, `data-parcel-error-overlay`, `data-v-inspector`, `data-screenshot-ignore="true"`) and `data-vite-dev-id` attributes, and supports `--unlock-scroll`.
- `src/core/designmd-snapshot-assets.ts` (`--inline-assets`, `--base-dir`, `--max-asset-bytes`) inlines local images/fonts in HTML attributes and CSS `url(...)` rules as `data:` URIs with descriptor-pinned reads and path-traversal guards.
- `src/core/rendered/capture-dom-snapshot.ts` (`--render`, `--browser`, `--viewport`, `--wait-ms`, `--inline-canvas`, `--flatten-iframes`) captures live DOM + `document.styleSheets` CSSOM bundles, converts readable `<canvas>` nodes to PNG `<img>` data URIs, and flattens same-origin `<iframe>` trees via zero-dep CDP.
- **Active-DS raw-hex leakage lint rule (`active-ds-token-leakage`) in `ui prompt-plan`**:
- `src/core/prompt-plan/prompt-plan-system-validation.ts` flags raw `#hex` literals in `visualSystem.palette` or `visualSystem.typography` when `activeDesignSystem: true` or `designSystemRef` is set outside `replicate` mode, paired with updated guidance in `knowledge/prompt-modes.md`, `templates/skills/apply-prompt-mode.md`, and `templates/workflows/generate.md`.
- **Codex plugin capabilities & manifest integrity checks**:
- `.codex-plugin/plugin.json` declares `"capabilities": ["Interactive", "Read", "Write"]`, documented in `README.md` and verified by `scripts/self_check.py` and `tests/plugin-manifests.test.ts`.

## 2026-11-16 - ease-design 0.7.2

TypeScript 7 toolchain, typed `ease-design/lint` declarations, and CLI UX fixes. Each item is described in full in its
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,8 @@ To keep `ui` on your path: `npm install -g ease-design`.

**Codex**

This repository also ships `.codex-plugin/plugin.json` for native Codex plugin discovery.

```bash
git clone https://github.com/jangtrinh/design-os.git /tmp/design-os
mkdir -p ~/.codex/skills/design-os ~/.codex/prompts
Expand Down
172 changes: 145 additions & 27 deletions knowledge/designmd-format.md
BD0
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,53 @@ description: "The DESIGN.md contract — the YAML token front-matter plus the ei
when: [designmd, design-md, token-frontmatter, google-labs]
---

# DESIGN.md format (Google Labs alpha)
# DESIGN.md format (Google Labs alpha & Stitch v1.0)

Pinned on-disk reference for the open-source DESIGN.md spec authored by
Google Labs. Read this instead of refetching the upstream repo each run —
the file the host model writes at project root must conform exactly to
what is described here.
Google Labs and the Stitch `DESIGN.md` v1.0 dialect. Read this instead of
refetching the upstream repo each run — the file the host model writes at
project root (or `.stitch/DESIGN.md`) must conform to the selected dialect
contract described here.

- **Upstream:** <https://github.com/google-labs-code/design.md>
- **Full schema:** <https://github.com/google-labs-code/design.md/blob/main/docs/spec.md>
- **Spec snapshot:** alpha (captured 2026-05-27). If the upstream repo has
moved to `beta`, this file is the contract — bump it explicitly rather
than letting the workflow drift.
- **Spec snapshot:** alpha (captured 2026-05-27) + `stitch` v1.0. If the
upstream repo moves to `beta`, this file is the contract — bump it
explicitly rather than letting the workflow drift.

A `DESIGN.md` file is **one document with two halves**:

1. A YAML front-matter block delimited by `---` on its own line, holding
the structured token data.
2. A Markdown body of **exactly 8 sections in a fixed order**, holding the
prose rationale a human (or another agent) reads.
2. A Markdown body with ordered `##` sections matching the chosen dialect,
holding the prose rationale a human (or another agent) reads.

Both halves are required. Either half alone is not a valid DESIGN.md.

---

## YAML front-matter schema
## Supported dialects (`alpha` vs `stitch`)

| Property | `alpha` dialect (default) | `stitch` v1.0 dialect (`.stitch/DESIGN.md` / `--dialect stitch`) |
|---|---|---|
| Output location | `./DESIGN.md` or `./<slug>/DESIGN.md` | `.stitch/DESIGN.md` (or `--dialect stitch`) |
| `version` field | Optional; `"alpha"` | Optional; `"1.0"` or `"stitch"` |
| `colors:` shape | 2-level nested `colors.<group>.<name>` | 1-level flat Material 3–style semantic roles (`surface`, `on-surface`, `primary`, `on-primary`, …) |
| `typography:` shape | 2-level nested `typography.<group>.<name>` | 1-level flat slot objects (`display-lg`, `headline-md`, `body-base`, `label-caps`) |
| `rounded:` / `spacing:` | Named radius (`sm`/`md`/`lg`/`full`) + numeric spacing scale | Includes `rounded.DEFAULT` and `spacing.unit` / `spacing.gutter` |
| `components:` | Optional object of `"{ref}"` token references | Optional (often omitted in Stitch v1.0) |
| Markdown body | **8 fixed `##` sections** | **6 ordered `##` sections** (numbered `## 1. ...` or unnumbered; 7-section `examples/DESIGN.md` layout also parses) |
| Contrast audit | Component `textColor` / `backgroundColor` pairs | Also pairs `<role>` / `on-<role>` colour tokens when `components:` is omitted |

---

## YAML front-matter schema (`alpha` dialect)

```yaml
---
name: "<brand or product name>" # required
description: "<one-line brand line>" # optional
version: "alpha" # optional; if present must be "alpha" at this snapshot
version: "alpha" # optional; if present must be "alpha" in alpha dialect

colors: # object of color tokens (group → name → value)
brand:
Expand Down Expand Up @@ -74,7 +90,7 @@ spacing: # object of spacing tokens (name → dime
"8": "32px"
"16": "64px"

components: # object of component definitions
components: # object of component definitions (optional)
button-primary:
backgroundColor: "{colors.brand.primary}"
textColor: "{colors.neutral.bg}"
Expand All @@ -89,18 +105,93 @@ components: # object of component definitions
---
```

### Required fields
### Required fields (`alpha`)

| Field | Required | Notes |
|---|---|---|
| `name` | yes | A short brand or product name. Free-form string. |
| `description` | no | A single line describing the brand voice or product. |
| `version` | no | If present at this snapshot, must be `"alpha"`. |
| `version` | no | In `alpha` dialect, must be `"alpha"` if present. |
| `colors` | as observed | Group → name → hex string. Omit if the source has no colour signal at all (rare). |
| `typography` | as observed | Group → name → object of typography properties. |
| `rounded` | as observed | Name → dimension. |
| `spacing` | as observed | Name → dimension. |
| `components` | as observed | Name → object using `"{ref}"` strings against the tokens above. |
| `components` | as observed | Optional. Name → object using `"{ref}"` strings against the tokens above. |

---

## YAML front-matter schema (`stitch` v1.0 dialect)

Use this dialect for `.stitch/DESIGN.md` or when `--dialect stitch` is passed to
`ui designmd audit`:

```yaml
---
name: "<brand or product name>" # required
description: "<one-line brand line>" # optional
version: "1.0" # optional; "1.0" or "stitch" in stitch dialect

colors: # 1-level flat Material 3–style semantic roles
surface: "#F9FAFB"
on-surface: "#0F172A"
surface-container-low: "#F1F5F9"
surface-container: "#E2E8F0"
primary: "#0F172A"
on-primary: "#FFFFFF"
primary-container: "#DBEAFE"
on-primary-container: "#1E3A8A"
secondary: "#334155"
on-secondary: "#FFFFFF"
tertiary: "#0D9488"
on-tertiary: "#FFFFFF"
error: "#DC2626"
on-error: "#FFFFFF"
outline: "#94A3B8"
outline-variant: "#CBD5E1"

typography: # 1-level flat slots
display-lg:
fontFamily: "Inter, sans-serif"
fontSize: "56px"
fontWeight: 700
lineHeight: "1.1"
letterSpacing: "-0.02em"
headline-md:
fontFamily: "Inter, sans-serif"
fontSize: "28px"
fontWeight: 600
lineHeight: "1.25"
body-base:
fontFamily: "Inter, sans-serif"
fontSize: "16px"
fontWeight: 400
lineHeight: "1.55"
label-caps:
fontFamily: "Inter, sans-serif"
fontSize: "12px"
fontWeight: 600
lineHeight: "1.3"
letterSpacing: "0.06em"

rounded:
DEFAULT: "8px"
sm: "4px"
lg: "16px"
full: "9999px"

spacing:
unit: "4px"
gutter: "24px"
"4": "16px"
"8": "32px"
---
```

When `components:` is omitted under the `stitch` dialect, `ui designmd audit`
checks WCAG contrast across `<role>` / `on-<role>` colour pairs (such as
`surface` / `on-surface`, `primary` / `on-primary`, `primary-container` /
`on-primary-container`, `secondary` / `on-secondary`, `tertiary` /
`on-tertiary`, `error` / `on-error`).

---

Expand All @@ -123,14 +214,14 @@ These are the only legal value shapes. Drift from them invalidates the file.
- `letterSpacing` (dimension string; optional)
- `fontFeature` (string of OpenType feature settings; optional)
- `fontVariation` (string of variable-font axis settings; optional)
- **Reference value.** A string of the form `"{group.name}"` that points
at another token defined above. Example: `"{colors.brand.primary}"`,
`"{typography.body.md}"`. References resolve at read time; circular
references are rejected.
- **Reference value.** A string of the form `"{group.name}"` (or `"{colors.primary}"`
for flat `stitch` roles) that points at another token defined above. Example:
`"{colors.brand.primary}"`, `"{typography.body.md}"`. References resolve at
read time; circular references are rejected.

---

## Markdown body — 8 sections, fixed order
## Markdown body — `alpha` dialect (8 sections, fixed order)

Section headings must be `##` level and must appear in this exact order.
Synonyms allowed by upstream are listed in parentheses; pick one per
Expand All @@ -152,25 +243,52 @@ document and use it consistently.
8. **Do's and Don'ts** — 3–5 bullets each, drawn from the cross-check
between observed HTML and the screenshot.

## Markdown body — `stitch` v1.0 dialect (6 ordered sections)

For `.stitch/DESIGN.md` (or `--dialect stitch`), emit these **6 ordered `##`
sections** (numbered `## 1. Visual Theme & Atmosphere` or unnumbered
`## Visual Theme & Atmosphere`):

1. **Visual Theme & Atmosphere** — visual mood, aesthetic temperature,
density, and surface personality.
2. **Color Palette & Roles** — semantic Material 3–style role table
(`surface`, `on-surface`, `surface-container-*`, `primary`, `on-primary`,
`secondary`, `tertiary`, `error`, `outline`, `outline-variant`) with hex
values and usage rules.
3. **Typography Rules** — slot table (`display-lg`, `headline-md`,
`body-base`, `label-caps`) with family, size, weight, line height, and
letter-spacing rules.
4. **Component Stylings** — surface treatments, corner radii (`rounded.DEFAULT`,
pills, sharp containers), border/elevation rules, and interactive states.
5. **Layout Principles** — `spacing.unit` / `spacing.gutter` rhythm,
container widths, responsive breakpoints, and whitespace proportions.
6. **Design System Notes for Stitch Generation** — concrete prompting rules,
anti-patterns to avoid, and invariant token bindings for generation.

> Note: The 7-section `Brand & Style` → `Colors` → `Typography` → `Layout & Spacing`
> → `Elevation` → `Shapes` → `Components` layout from upstream
> `examples/DESIGN.md` also parses under the `stitch` dialect.

### Section-ordering rules

- All 8 sections are required. An emitted DESIGN.md with a missing
section is invalid.
- All sections required by the active dialect (8 for `alpha`, 6 for `stitch`)
must be present. An emitted DESIGN.md with a missing section is invalid.
- Duplicate headings reject the whole file. Each `##` heading must be
unique.
- Unknown `##` headings inserted between the spec sections are preserved
(the spec is extensible) but disrupt the canonical reading order — do
not emit them from this workflow.
- Heading text matches the spec exactly. Capitalisation and apostrophes
matter: `Do's and Don'ts`, not `Dos and Donts`.
- In `alpha`, heading text matches the spec exactly. Capitalisation and
apostrophes matter: `Do's and Don'ts`, not `Dos and Donts`.

---

## Versioning and extension rules

- The current spec version is **`alpha`**. `version: "alpha"` is optional
in the YAML; if present it must be exactly `"alpha"`. Do not emit
speculative version strings like `"beta"`, `"v1"`, or `"latest"`.
- In `alpha` dialect, `version: "alpha"` is optional in the YAML; if present
it must be `"alpha"`. In `stitch` dialect, `version` if present must be
`"1.0"` or `"stitch"`. Do not emit speculative version strings like
`"beta"` or `"latest"`.
- Unknown YAML keys at the top level are preserved by lenient readers
but cannot be referenced. Do not invent new top-level keys from this
workflow.
Expand Down
31 changes: 31 additions & 0 deletions knowledge/prompt-modes.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,37 @@ leaves the builder to invent product and layout decisions.
Compile and validate the prompt plan before emitting the seven-layer builder frame. The frame is
the compact execution packet; the prompt plan is the inspectable source of its decisions.

### Active-DS token-leakage boundary

When a project has an active `design/` store (`dsStatus === "present"`) or an active `DESIGN.md` /
`.stitch/DESIGN.md` (`activeDesignSystem: true` / `designSystemRef` in `prompt-plan`), generation
and enhancement prompts MUST reference semantic token roles and registered component names — strip
raw `#RRGGBB` hex codes, raw `font-family` names, and ad-hoc pixel radius or palette overrides from
the prompt so they cannot conflict with the active design system.

Exceptions: `replicate` mode when no project DS is active, or an explicit single-element colour edit
override requested by the owner. (`ui prompt-plan validate` enforces this boundary via
`active-ds-token-leakage`.)

### Natural-to-UI structural & physical terminology

Translate vague user phrasing into explicit structural UI terms and physical shape/elevation
descriptors before compiling `prompt-plan` / RODES:

| Natural user phrasing | Structural UI translation |
|---|---|
| "menu at the top" | Sticky navigation bar with brand mark and primary nav items |
| "big photo / banner" | Hero region with focal media, headline hierarchy, and primary CTA |
| "list of things" | Responsive card grid or structured data list with explicit hover/focus states |
| "popup" | Modal dialog with backdrop scrim, focus trap, and dismiss control |

Shape & elevation descriptors:

- **Radius:** `0px` → sharp, squared-off edges; `4px` → slightly softened corners; `8px` → gently
rounded corners; `12–16px` → generously rounded corners; `9999px` → pill-shaped.
- **Elevation:** `none` → flat border-delineated surface; subtle `sm` → whisper-soft ambient shadow;
high `lg` → floating modal/popover layer.

### Failure Modes

Where this contract goes wrong:
Expand Down
10 changes: 5 additions & 5 deletions schemas/template-descriptions.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
{
"path": "skills/apply-prompt-mode.md",
"description": "Decide how faithfully to track a reference input. Use when a workflow consumes a screenshot, URL, or Figma frame and must choose between faithful reproduction and inspired reinterpretation.",
"sourceSha256": "fd999d84cb87170b8267f0e4c2c7577faddb96791afea77c5fd4af5263336e94"
"sourceSha256": "cfdc5d36e984522b12e8e8b57109272350b9776b72d572a53d4bd4d68b8d905e"
},
{
"path": "skills/canvas-effect.md",
Expand All @@ -44,7 +44,7 @@
{
"path": "skills/designmd-emit.md",
"description": "Compose a DESIGN.md file from harvested tokens, observed components, and a chosen persona family. Use inside the from-url workflow when writing the 8-section Google-Labs-spec DESIGN.md.",
"sourceSha256": "6bc6bba68ed7aa4859ef7f57b7c1b1ee37749be1f1bc5129f52ca9ca05cbce81"
"sourceSha256": "ae756b3901f51fce13e0f009f8d7648d80dfd75662f55e10b3365f6db48280cf"
},
{
"path": "skills/diagram-craft.md",
Expand Down Expand Up @@ -139,7 +139,7 @@
{
"path": "workflows/extract.md",
"description": "Extract a design system from existing HTML. Use when the user provides HTML and wants its tokens and components harvested into a project design system.",
"sourceSha256": "c01b9d57785e403477db6897990ac1b39e9a8b241ef8113bb6d23dbe6924a0b0"
"sourceSha256": "0c3c1c62e9eb853f69f623c2a339bd4a3c69e5c7a2e4d8e73e28822de04c0b88"
},
{
"path": "workflows/figma-comments.md",
Expand All @@ -159,12 +159,12 @@
{
"path": "workflows/from-url.md",
"description": "Extract a portable DESIGN.md spec folder from a live URL. Use when the user points at a website and wants its design system captured for reuse.",
"sourceSha256": "8b40ae5d9781ca59094ef9aefa5977d0f942fa4af1f3463e287a08ee61e72167"
"sourceSha256": "e822900c35ab5a20175e50d93adb56c1b5f0db0c28eb02dd9339f5720e9b9122"
},
{
"path": "workflows/generate.md",
"description": "Generate evidence-qualified marketing or landing-page HTML. Use when web-marketing capability activation succeeds for a plain-language request or visual reference.",
"sourceSha256": "25bacca9e68092c82b5ad32aead432dd11f2548686efb0ce664ff7416cf7fe05"
"sourceSha256": "162098edc87eb6758a0191a7a02a6465a59f60876b2dedd136ab7b80e01f099d"
},
{
"path": "workflows/guidelines.md",
Expand Down
Loading
Loading
0