Ruby For Good's global design system. Any application in the Ruby For Good ecosystem (or outside
it) can migrate its UI onto this system using design.md, the design
tokens, the executable audit suite, and the Claude Code skills in
.claude/skills/. Start with the design-system-migration skill: it's the
step-by-step playbook (spec first, research precedent, preview before building, apply app-wide,
enforce with an executable audit) for migrating an app onto this system.
Unlike most design systems you can install, this one was built the other way round: every rule in
design.md started as a real defect, found on a real, running application, fixed, and enforced
with an executable check, not derived from first principles and hoped to hold up.
docs/field-notes.md is the evidence trail; docs/portability/ is the record of proving each rule
portable beyond the app it was first found on, including where it turned out not to be, yet.
design.md |
The spec. Every rule is tagged Portable (holds on any app) or Local (this project's own answer: the practice of deciding may transfer, the specific value doesn't). See docs/portability/design-md-tagging.md for the full breakdown. |
tokens/ |
Design tokens as a Tailwind v4 @theme block: colour, type, spacing, radius, elevation, with the Portable rule and the Local default value stated separately for each. |
bin/design/ |
~40 executable audits (WCAG conformance, copy quality, dead code, and more) built on an adapter seam: point one small file (targets.js) at your app and most of the suite runs unmodified. |
examples/reference-app/ |
A second, deliberately non-Rails adapter target: proof (and, honestly, some disproof) that the adapter claim holds. See docs/portability/adapter-reference-app.md. |
docs/field-notes.md |
The evidence index: what's measured, what's historical, and the rule for not citing another app's own numbers as claims about your app. |
docs/portability/ |
The genericization work itself: what's proven portable, what's still Local, what's an honest known gap. |
.claude/skills/ |
The methodology as Claude Code skills: design-system-migration, audit-suite, wcag-conformance, evidence-discipline, session-durability. Not published to npm; available in this repository. |
Load the design-system-migration skill in Claude Code and point it at the app you're migrating.
It works from design.md as the normative spec, researches how the app's current UI compares,
previews changes before building them, applies fixes app-wide rather than screen-by-screen, and
wires up an executable audit so a fixed defect can't silently come back. audit-suite and
wcag-conformance are the supporting skills it leans on for building checks you can trust and for
WCAG 2.2 conformance specifically.
Not on the npm registry yet (see Status below), but installable right now straight from GitHub:
npm install github:rubyforgood/designsystem/* your Tailwind entry point */
@import "@rubyforgood/design-system/tokens/theme.css";Once this is published to the registry, npm install @rubyforgood/design-system will work the
same way and this page will be updated to lead with that instead.
That gives you the shipped default palette (indigo, Figtree, a 4px scale). Retheme by overriding
the same token names; see tokens/README.md for which parts are load-bearing
rules and which are just this default's answer.
The audits aren't a library you import: Node's module resolution plus the adapter pattern
means you copy an audit file into your own project, next to your own adapter. This is
deliberate, not a packaging shortcut: bin/design/adapters/reference-app/ and
bin/design/targets.js are two full worked examples of exactly this.
- Write a
targets.js(or whatever you name it) implementing the nine-export contract:BASE,PASSWORD,targets(),signIn(),visit(),RUNS,SECONDARY,ADMIN,PRIMARY. Seebin/design/targets.js(a Rails/Devise adapter) andbin/design/adapters/reference-app/targets.js(a zero-framework Node adapter) for two different real implementations of the same contract. - Copy the audit(s) you want from
bin/design/into the same directory as your adapter. - Run them:
node keyboard-audit.js, etc.
bin/design/README.md documents every audit: what it checks, why it's built the way it is, and
what false positives it already survived. Not every audit is confirmed portable yet; read
docs/portability/audit-tooling-classification.md
before assuming one that hasn't been tested against a second adapter will just work.
Early. design.md has been fully passed over once for the Portable/Local split; the audit suite
has real, measured portability evidence for 22 of ~40 scripts (see
docs/portability/adapter-reference-app.md) and
documented, not-yet-attempted plans for the rest. .github/workflows/checks.yml runs syntax
checks, a doc-link audit, and a regression check against the reference app on every push.
This has not been published to the npm registry yet; install straight from GitHub in the meantime (see "Using the tokens" above).
This system began inside Human Essentials, Ruby For Good's inventory-management app, as that app's own internal design system, built rule by rule against real defects on real screens. It was forked out and genericized into this independent, adoptable project; see ADR 13 for that decision and what genericizing it actually involved.
MIT, see LICENSE. Carried forward from
Human Essentials, also MIT, also Ruby for Good.