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, an installable component layer built as Web Components, 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. |
components/ |
An installable Web Components layer (Lit) implementing design.md's Components section in code — npm install-able or copy a single standalone file. Early: only <rfg-button> exists so far. See ADR 14. |
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, a regression check against the reference app, and (since the component
layer) a components/Storybook build plus a real accessibility/keyboard audit run — all on every
push. The
component layer is newer still: twenty-five components built — button, status-pill,
icon-tile, avatar, card, flash-message, page-header, tabs/page-tabs, modal,
popover, field, error-summary, table, date-range-picker, stats, numbered-step,
callout, disclosure, empty-state, breadcrumbs, conditional-reveal, filter-bar,
pagination, tag-input — every genuinely portable component in design.md's catalog except
Charts (deliberately not ported; it defers entirely to Highcharts itself, so there's no generic
rule to extract beyond usage guidance). Each is verified in a real browser against the
accessibility rules its own design.md section documents, previewable via Storybook
(npm run storybook) with an axe-core a11y gate on every story, and audited for real —
wcag-audit.js and keyboard-audit.js run against the built Storybook site in CI (a third
adapter, bin/design/adapters/storybook/, see docs/portability/adapter-storybook.md). See
components/README.md and
ADR 14.
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.