design-md

@subsimplicity/pi-extension-design-md is a pi extension that gives agents first-class access to Google's DESIGN.md visual identity specification while they work on UI code.

Features

• Finds the nearest DESIGN.md or design.md by walking up from pi's current working directory.
• Injects DESIGN.md context into pi's system prompt for design-related requests only.
• Registers tools for onboarding, linting, exporting, previewing, and reading the formal DESIGN.md spec.
• Re-lints DESIGN.md/design.md after pi write or edit tool changes and appends findings to the tool result.
• Shows a design: status indicator in pi:
  • design: none when no design file is found.
  • design: ✓ DESIGN.md when lint passes without warnings.
  • design: ! DESIGN.md when warnings are present.
  • design: ✗ DESIGN.md when errors are present or linting fails.

Prompt injection runs in auto mode. DESIGN.md context is added only when the user request appears related to UI/design work, including styling, frontend changes, components, layout, colors, typography, spacing, Tailwind/CSS, accessibility, and similar topics. The DESIGN.md tools remain available at all times.

Requirements

• Bun for local development in this repository.
• pi with extension/package support.

Install / use locally

From this package directory:

bun install
pi -e ./src/index.ts

To install from a local checkout so pi loads it automatically:

pi install ./path/to/design-md

Use a project-local install when you want pi to record it in that project's .pi/settings.json:

pi install -l ./path/to/design-md

Tools

Tool	Purpose
designmd_onboard	Start a DESIGN.md onboarding flow with discovery questions, generation guidance, and optionally a valid starter DESIGN.md file.
designmd_lint	Validate a DESIGN.md file and return findings, resolved tokens, sections, and summary data.
designmd_export	Export tokens to a file as Tailwind v3 JSON (json-tailwind or tailwind), Tailwind v4 CSS @theme (css-tailwind), or DTCG JSON (dtcg).
designmd_preview	Generate a standalone HTML preview with palette, typography, spacing, radius tokens, component samples, and lint findings.
designmd_spec	Return the formal DESIGN.md specification, optionally with the active lint rules.

Most tools accept either a path to a DESIGN.md file or raw content. When neither is provided, the nearest DESIGN.md/design.md from the current working directory is used.

Tool parameters

• designmd_onboard: { projectName?, productDescription?, audience?, personality?, existingBrand?, visualReferences?, constraints?, createStarter?, outputPath?, force? }
  • by default it returns onboarding questions and a starter draft in the tool result
  • set createStarter: true to write a starter file, defaulting to ./DESIGN.md
  • set force: true to overwrite an existing output file
• designmd_lint: { path?, content? }
• designmd_export: { format, path?, content?, outputPath? }
  • format: json-tailwind, tailwind, css-tailwind, or dtcg
  • outputPath defaults to ./design-md-tailwind.json, ./design-md-tailwind.css, or ./design-md-tokens.json depending on the format
• designmd_preview: { path?, content?, outputPath?, title? }
  • outputPath defaults to ./design-md-preview.html
• designmd_spec: { rules?, rulesOnly? }

Commands

• /designmd-onboard — start interactive onboarding by having the agent ask discovery questions one at a time without dumping the full brief into chat.
• /designmd-onboard write [path] — write a valid starter file, defaulting to ./DESIGN.md.
• /designmd-onboard force [path] — overwrite an existing starter file.
• /designmd-lint [path] — lint the nearest or specified DESIGN.md/design.md.
• /designmd-export <json-tailwind|tailwind|css-tailwind|dtcg> [path] [--out outputPath] — export tokens from the nearest or specified design file directly to a file without dumping the export into chat.
• /designmd-preview [output.html] — generate a visual preview HTML file from the nearest design file. Defaults to ./design-md-preview.html.
• /designmd-spec — add the DESIGN.md spec to the transcript.
• /designmd-spec rules — add active lint rules only.
• /designmd-spec with-rules — add the spec plus active lint rules.

Typical workflow

1. Run /designmd-onboard to have pi collect brand/audience/context answers interactively, or /designmd-onboard write to create a starter DESIGN.md.
2. Add or update DESIGN.md in your project.
3. Run /designmd-lint to validate it.
4. Ask pi to implement UI work; design-related prompts automatically receive DESIGN.md context.
5. Run /designmd-preview to inspect the identity in a browser.
6. Export tokens to files with designmd_export or /designmd-export when wiring DESIGN.md into Tailwind, CSS theme variables, or design-token JSON.

Development

bun install
bun run typecheck

Useful scripts:

• bun run typecheck — TypeScript type checking.
• bun run lint — run ESLint with fixes.
• bun run format — format the repository with Prettier.

Use Bun for package management and scripts in this repo.