Skip to content

Contributing

Adding a token

Ask first whether it can be derived. If two values must move together, one should be computed from the other — that is the whole architecture.

If it genuinely is a new independent decision, it is a knob: add it to knobs.css, in the right /* ---- section ---- */ (the generator reads those headers as the grouping), with a comment saying what it reaches and why it is not derived. Then:

abilian-ds tokens          # regenerate TOKENS.md

Adding a component

  1. Put it in the right parts/ file, or add a new one — ads.css @imports it in alphabetical order, and a part may depend only on tokens.
  2. No literals. No colour, length, radius or shadow that is not a var(). If the value you want does not exist, that is the signal to add a token, not to write 12px.
  3. Carry state as an attribute. If a person can perceive the state, key the CSS off aria-current, aria-pressed, aria-invalid or aria-expanded rather than a class.
  4. Use it somewhere, or unused-class will flag it — correctly.
  5. Add it to the reference application so the browser sweep covers it.

Adding a lint rule

When something ships wrong, the fix is usually a rule. Rules live in lint.py and each gets a docstring saying what shipped that motivated it — that is what stops the next person deleting it as over-engineering.

Scope new rules to the system's prefix where it makes sense; a project's own utilities are its own business, and a vendored third-party sheet is not ours to tidy.

Before you push

make check                 # library
cd poc && make check       # everything else, including calibration

Calibration needs the demo on :8080:

cd poc && make run

House style

  • Comments explain why, not what. display: flex needs no comment; "layout.css loads last because both selectors are one class and the component would otherwise win" does.
  • Record what was wrong first. Several comments in this codebase say "this was X and X was wrong because…". They are the most valuable lines in the file, because they stop the mistake being reintroduced as a simplification.
  • Never silence a checker. No # noqa, no exclusion. If a violation is intentional, explain it inline; if there are many, the structure is wrong.