Foundations
What the language holds to, and who it has to work for.
Principles
Eight decisions, in the order they get used. Each one is written so it can be applied or violated on a specific line of code, because a principle you cannot check is a mood.
- 1Documents, not dashboardsThe audience is a VA or an agency operator doing a job, and the job is not admiring the interface. Pages read like a well-set document: one clear title, generous space, a small number of type sizes, and no ornament that is not carrying information.
- 2One accent per blockBrand pink marks the one thing in a section that matters most. Two pink things in one block means neither is emphasised. This is the rule most often broken by adding a feature, and the easiest to check.
- 3Glass is structure, not decorationFrosted surfaces say 'this floats above the page': the shell, menus, dialogs, page-interior cards. A surface that does not float does not get glass, because if everything is glass then nothing reads as raised.
- 4Motion is feedback, not performanceOne orchestrated entrance per page mount, consistent hover and press feedback everywhere something is interactive, and nothing looping on a work surface. If an animation is not telling the user something, it should not be there.
- 5Tokens, never literalsNo hex, no Tailwind palette literals, no re-declared easing curves. Every colour comes from a semantic token and every curve from lib/ui/motion-tokens. A literal is a value that cannot follow the theme or the team palette.
- 6Match the nearest surfaceWhen a spacing step, a radius, or a shade is not obvious, copy the closest existing surface rather than picking a new value. The system is held together far more by that habit than by any rule written down.
- 7Say what happens nextEvery string a person reads while something is going wrong should tell them what to do about it. 'An error occurred' fails this; 'That team name is already taken. Try another.' passes.
- 8The catalog cannot lieThis page renders the real components and reads the real tokens out of the running document. Anything documented with a screenshot or a hardcoded value would start drifting the day it was written.
Accessibility
Not a checklist bolted on at the end. Four things are load-bearing in this system, and each one is visible on this page rather than asserted.
Focus rings come from --ring, which is a colour-mix of --brand, so a team with its own colour gets its own focus ring. Tab through these; the ring is 3px at 45% opacity, which clears the surface it sits on in both themes.
Your prefers-reduced-motion is currently no-preference. The Motion chapter shows what each animation does under both.
An entrance that starts at opacity 0 and is then switched off leaves a blank page. Every gate in this product ends at the finished state, so the interface arrives complete and immediately.
A status dot is always paired with a word. Anyone who cannot separate the two hues reads the label instead, and everyone else reads the dot faster than the label.
Wherever the rosette sits beside the word Phloom, the symbol is aria-hidden and the live text is the accessible name. PhloomMark takes title={null} for exactly this case, and defaults to 'Phloom' when it stands alone.
How to use this
Five chapters, one per petal. Each one shows the real components and reads the real values, so anything here can be quoted in a review with a link rather than a screenshot.
- BrandThe mark, the wordmark, and how Phloom talks.
- ColorTwo gardens, one palette, and the glass between them.
- Type & SpaceThree families, one scale, and the rhythm they sit on.
- MotionTwo curves, a handful of beats, and when to hold still.
- ComponentsEvery primitive we ship, live and interactive.
The written companion is docs/design-language.md, which covers the same ground in a form you can read in a diff and links every historical design spec that decided a piece of it.