docs: Add DESIGN-MD-PROMPT.md for consumer repos - #865
Open
ledfut wants to merge 1 commit into
Open
Conversation
Adds docs/DESIGN-MD-PROMPT.md — a copy-pasteable prompt for coding agents (Claude Code, Cursor, Gemini CLI, etc.) that bootstraps a google-labs/design.md-compliant DESIGN.md *plus* a generator pipeline in any consumer repo of @lukso/web-components. Why this lives here, in the library repo: the prompt's job is to tell agents how to integrate this library. Keeping it next to the library itself means the prompt and the library version evolve together — bumping the LUKSO scale, adding a new <lukso-*> component, or restructuring the typography classes can be reflected in the prompt in the same PR. How consumers use it: paste the fenced markdown block in 'The prompt' section into an agent session opened inside the *consumer* repo. The agent emits scripts/generate-design-md.mjs + a project config + DESIGN.md at the consumer's repo root, wires it into pre-commit and CI, and validates against the spec linter. Reference implementation: universaleverything.io adopted this pattern in PR #780 — link from the prompt for a worked example.
Contributor
Storybook deployed with Cloudflare Pages ☁️ 📖 🚀Storybook
Built from commit d8f2e30 |
dzbo
reviewed
Apr 27, 2026
Comment on lines
+22
to
+27
| **Reference implementation:** [universaleverything.io](https://github.com/universal-everything/universaleverything.io) is the canonical example — | ||
|
|
||
| - [`DESIGN.md`](https://github.com/universal-everything/universaleverything.io/blob/main/DESIGN.md) — the generated artifact | ||
| - [`scripts/generate-design-md.mjs`](https://github.com/universal-everything/universaleverything.io/blob/main/scripts/generate-design-md.mjs) — the generator | ||
| - [`scripts/design-md.config.mjs`](https://github.com/universal-everything/universaleverything.io/blob/main/scripts/design-md.config.mjs) — project-specific role mapping | ||
| - [`.husky/pre-commit`](https://github.com/universal-everything/universaleverything.io/blob/main/.husky/pre-commit) — auto-regenerate hook |
Collaborator
There was a problem hiding this comment.
We shouldn't mention outside repos here, docs should stay generic
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new copy-pasteable agent prompt (docs/DESIGN-MD-PROMPT.md) intended for consumer repos of @lukso/web-components to bootstrap a spec-compliant DESIGN.md plus an automation pipeline to keep it in sync.
Changes:
- Add
docs/DESIGN-MD-PROMPT.mddocumenting a 7-step agent workflow to generate and validateDESIGN.md. - Include guidance for scanning
<lukso-*>usage and in-repo custom components, plus hook/CI integration. - Provide reference links and a validation checklist for consumers.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+130
to
+135
| ```bash | ||
| yarn design:generate # writes DESIGN.md | ||
| yarn lint:design # exit 0 ⇒ committed file matches sources | ||
| npx @google/design.md lint DESIGN.md # spec validation, expect 0 errors | ||
| yarn lint:fmt # prettier-clean across the new files | ||
| ``` |
| yarn lint:fmt # prettier-clean across the new files | ||
| ``` | ||
|
|
||
| Target: `errors: 0` from the spec linter. Warnings are acceptable when they stem from upstream LUKSO values (e.g. `button-primary-hover` using `lukso-60` `#bb7793` for hover, `status-error` using `red-55` `#e23636`). If the linter flags any other warnings, fix them in the role mapping or component recipes — never silently accept them. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/DESIGN-MD-PROMPT.md— a copy-pasteable prompt for coding agents (Claude Code, Cursor, Gemini CLI, Aider, etc.) that bootstraps both aDESIGN.mdand a generator pipeline that keeps it in sync in any repo consuming@lukso/web-components.The
DESIGN.mdformat itself is the google-labs/design.md spec — a YAML-front-matter + prose contract that gives coding agents a stable, token-addressable description of the consumer product's visual identity.No code changes. Single new file at
docs/DESIGN-MD-PROMPT.md(163 lines). Zero impact on the library's build, tests, or runtime.Why this lives here
The prompt's job is to tell coding agents how to integrate this library. Keeping it next to the library means the prompt and the library version evolve together — bumping the LUKSO scale, adding a new
<lukso-*>component, restructuring the typography classes, or moving the radius/spacing tokens to a different file can all be reflected in the prompt in the same PR. Consumersgit pull-ing the library get the up-to-date integration playbook by default.What the prompt does
When pasted into an agent session inside a consumer repo, the agent:
@lukso/web-componentsis inpackage.json.node_modules/@lukso/web-components/dist/styles/{colors,typography,component}-v4.cssfor token values.<lukso-*>library usage across the consumer's templates.scripts/generate-design-md.mjs+ a project config +DESIGN.mdat repo root, with HTML comment fence markers around the dynamic sections so evergreen prose stays human-curated.package.json, pre-commit hook, and CI (yarn lint:designas a parallel sub-lint).npx @google/design.md lint DESIGN.mdand the consumer's formatter.Reference implementation
universal-everything/universaleverything.io#780adopts this exact pattern. That PR'sDESIGN.md,scripts/generate-design-md.mjs,scripts/design-md.config.mjs, and.husky/pre-commitare a worked example of the shape this prompt produces.Use cases
<lukso-button variant="primary">plus the consumer's existing<AppLink>/<ProfileCard>/<TokenCard>wrappers as the canonical implementations and stop hand-rolling primitives in Tailwind.DESIGN.mdplus the pipeline that keeps it in sync, in one agent session.npx @google/design.md diffbetween releases of this library can surface token-level breaking changes.DESIGN.mdfiles become first-class inputs to Figma, Style Dictionary, and other design-tooling pipelines via--format tailwind/--format dtcg.How to test
Render the file on GitHub and confirm:
tools-web-components.pages.dev),universaleverything.io, and the npm package.npx prettier --check docs/DESIGN-MD-PROMPT.md.To dry-run the prompt itself: clone any LUKSO dApp that doesn't yet have a
DESIGN.md, paste the fenced block from the file into a fresh agent session, and verify the agent produces a working pipeline. Iterate on the prompt here when it doesn't.Follow-ups (not in this PR)
README.mdand/orCLAUDE.mdpointing at this file so consumers discover it.alpha, revisit the prompt's "Validate" step to drop the warning-tolerance language.