Rationale

The four rules this system's build actually enforces, and the one thing about it that is not arbitrary.

Where this comes from

Gloss is a name and nothing more — it is not an argument about the system. The argument is in the umbrella it belongs to. Arbitrary Definitions is a personal umbrella for side projects — self-hosted, single-user tools built for one household or one person, never a SaaS product. Almost nothing in a design system is derived: the accent is teal because someone liked it, the type scale ratio is 1.20 at the small end and 1.25 at the large end because that is what looked right, not because either number is correct. What makes it a system is not that the choices are correct but that they were written down once, given names, actually used, and are therefore changeable.

What actually makes it a system

Not the quality of the individual choices. The properties below:

It is written down once

One hand-maintained stylesheet of custom properties. Not a Figma library that disagrees with the CSS, and not a spreadsheet somebody exports by hand.

It has names

--gl-color-danger survives a change of mind about which red. #ad3a2c does not.

It is actually used

Every color, type, spacing, radius, elevation, and motion value in the components is a var(--gl-*). Not one is a literal.

It can be changed

Because of the three above, swapping the accent for Clay, Ochre, Ink Blue, or Plum is a one-line diff.

The one thing that is not arbitrary

Contrast. A ratio is a physical fact about two colors and a pair of eyes, and it does not care what the brand guidelines say.

So it is the one thing this system checks rather than eyeballs. Five pairings have to hold, computed once from the token values with the standard WCAG 2.1 relative-luminance formula and written down as fact on the contract table rather than re-derived on every build — a personal site does not need a test suite standing between an edit and a deploy to keep five numbers honest.

That contract is deliberately narrower than “every color in the system”. --gl-color-text-tertiary — this palette’s own “muted-faint text” step — is about 3.46:1 against the page in light mode, under the 4.5:1 floor for normal text. That is not a bug to paper over by darkening a real brand value; it is a documented, intentional property of the palette (see the Color page), so the contract excludes it rather than silently forcing it to pass. Dividers get the same treatment for the same reason: this system’s own rule is that a bounded surface reads by surface contrast, not by a border, so hairlines are reserved for dividers inside a surface and this contract does not invent a 3:1 assertion for a boundary the system doesn’t draw.

The four rules

1. No color and no duration outside tokens.css

A hex or a duration in a component stylesheet is a decision made in the dark, and it is the kind that breaks the moment somebody adds a theme. No component stylesheet in this repository contains either; the one flagged exception is Select's chevron, which CSS cannot point at a custom property inside a data-URI, and it is commented as such.

2. Components read aliases, never ramps

--gl-color-text-primary, not --gl-neutral-900. The ramp is raw material; the alias is the decision. This is the whole reason the dark theme is a block of repointed aliases rather than a second stylesheet.

3. Every token says what it is for

Every semantic alias on the Color page carries a usage note. A token nobody can describe is a token nobody will use correctly.

4. One accent, one dark-mode convention

Never two accents in one view. Dark mode is opt-in — a data-theme toggle plus prefers-color-scheme, never inherited silently from the OS alone.

What this system does not have

Being honest about the design is being honest about the gaps too.

No formal component library or Figma file exists. The sixteen components documented here are a from-scratch, best-guess personal-tool kit — not a literal recreation of any real app’s screens, and not backed by a source of truth beyond this site.
No logo or brand mark. Render “Gloss” or the project’s own name in type wherever a mark would go — don’t invent one.
The icon set (Lucide) is a flagged substitution — there’s no shipped icon library of its own yet.
Signal Teal, the default accent, is one pick among the sanctioned alternates, not a fixed identity.
No Table, Callout, or Progress component. An earlier pass at this site invented all three; they were removed rather than kept, since this system doesn’t define them. (This documentation site still uses a plain <table> and an aside box for its own reference material — those are site chrome, not system components, and are not documented as one.)
Loop and Archive are generic demonstrations, not real production screens.

Naming these is cheaper than being caught by them. For the shapes this system actively refuses to reproduce when a new screen is built on top of it — kickers, icon tiles over headings, pulsing status dots, and the rest — see Refusals.