DocuBuild design guidelines
Read this first when you build or change UI in a DocuBuild product app. These files ship inside @docubuild-io/design, so the rules here are versioned with the tokens and components they describe. The design system’s preview site renders these same files.
Status
Phase P0. The token pipeline and the contrast gate exist. The only token set is Today, a record of the values the apps ship now, and nobody adopts it. The visual direction is chosen in P1. The guidelines below fill in from P2 onward, with the first real release (0.1.0).
Rules that already hold
- Write roles, never palette colours. Use a semantic role such as
text-ink,bg-panel,border-lineortext-ok. Never writetext-gray-500, a hex literal or an arbitrary pixel size liketext-[13px]. A product repo’s ratchet fails a pull request that adds any of them. - Every text pair meets WCAG AA. Body text needs 4.5:1. Large text and non-text UI, such as input borders and the focus ring, need 3:1. The token build fails when a role pair misses its minimum. Do not work around it with a hand-picked colour.
- One brand colour for every app. An app is told apart by the product badge in its logo lockup, never by an accent colour of its own.
- Nouns are not here. What things are called, such as roles, records and the customer’s word for an organisation, lives in each product repo’s
CONTEXT.md. These guidelines cover how things look, behave and are worded, independent of any one product. - This package is public. Never put customer names, project names, people or internal decisions in these files or in any sample data. Invent production-length data instead.
Coming with 0.1.0
| File | Covers |
|---|---|
foundations.md | Roles, the type scale, spacing, radius, elevation, layers, motion and the contrast rule |
from-shadcn.md | Translation table from shadcn names (text-muted-foreground, bg-primary …) to roles |
writing.md | How UI text is written: buttons name the record outcome; a refused action states its reason; empty states; sentence case |
interaction.md | Refused actions greyed out with a reason, never hidden; dialogs that scroll inside; size variants and touch targets |
mockups.md | Hi-fi mockups drawn from these components with production-length data, and promotion into the system |
components/*.md | One page per component: when to use it, its anatomy, do and don’t |