# Design.md authoring references

Consult these when revising the skill or resolving questions about the guide's scope. These are authoring sources, not dependencies for generated guides.

- [How our agents build on-brand pages with design.md](https://vercel.com/blog/how-our-agents-build-on-brand-pages-with-design-md), read November 13, 2026.
- [Supplied design-language example](https://github.com/educlopez/design-bites/blob/main/design-mds/vercel.com/DESIGN.md), read November 13, 2026.
- [OpenAI skill guidance](https://developers.openai.com/codex/skills), read November 13, 2026.
- [OpenAI latest-model guidance](https://developers.openai.com/api/docs/guides/latest-model), read November 13, 2026.

## Lessons adapted from the article

A portable guide supplies the judgment that repository context normally provides. Include scope, the reader's task, observable design decisions, and available primitives. Hierarchy and composition matter alongside visual styling. The same vocabulary should support different layouts for different tasks.

Use concrete rules instead of adjectives. Keep reusable mechanics in tokens or existing styles when appropriate. Improve guidance from observed failures rather than accumulating speculative rules.

When evaluating generated pages, keep the prompt, inputs, model, and viewport fixed. Save the baseline and compare first attempts with and without the guide. Check measurable behavior separately from human judgments about composition. One comparison provides evidence about that case, not reliability.

## Greenfield adaptation

The capture is a lightweight input for future products. It does not require an existing brand, hosted stylesheet, evaluation harness, or component library. Encode a small semantic vocabulary directly in the guide. Record estimates and proposed defaults separately from measured source values.

Use the supplied example's role-based tables and component-state detail selectively. Its branded identifiers, exhaustive inventories, inferred philosophies, and source-specific rules are not portable defaults. Verify observations independently for each capture.

A routine capture ends with document review. For a requested implementation or correction, use [application-review.md](application-review.md). Keep review artifacts separate from the portable guide.

## Surface scope

A public website and its product can share identity while using different typography, density, controls, and composition. An observed failure applied editorial website rules to a working dashboard. The correction used a supplied product screenshot, separated surface-specific rules, and compared rendered layouts. Capture scope before values so a later implementation can select the supported treatment. This lesson does not establish universal dashboard styling or require a particular component library.
