Skip to main content

Contributing

How to add to the system so the compiler picks it up and consumers can use it. After any change, run check_design_system and fix what it reports.

How the compiler sees the project​

  • Global CSS is styles.css (an @import manifest). Tokens and @font-face are read from its closure.
  • A component = a Name.d.ts (PascalCase) plus a sibling Name.jsx in the same folder. It compiles into _ds_bundle.js and is exposed at window.PrismDesignSystem_39d121.Name.
  • A specimen / doc card = an .html whose first line is <!-- @dsCard group="…" viewport="WxH" name="…" subtitle="…" -->. It renders in the Design System tab, grouped by group.
  • Never hand-edit _ds_bundle.js, _ds_manifest.json, or _adherence.oxlintrc.json — they are regenerated every turn.

Add a component​

  1. Create components/<group>/<Name>.jsx. Plain React. Styling = tokens-only, applied via a prism-* className.
  2. Add its CSS to components/<group>/<group>.css and ensure that file is @imported in components/components.css.
  3. Write components/<group>/<Name>.d.ts — exact prop types (this is the contract).
  4. Write components/<group>/<Name>.prompt.md — what it's for, when to use it, a code example, and a Status: line (maturity).
  5. Add or update the group's .card.html specimen (load ../../_ds_bundle.js, read from the namespace).
  6. Add the component to the README index.
  7. check_design_system → fix → repeat until clean.

Naming: PascalCase exports; prism-<component> / prism-<component>-<part> classes. Only capitalised exports reach the window namespace.

Add a token​

  1. Put it in the right tokens/*.css file (colour → colors.css, etc.). Define both light and dark values if it's a semantic colour.
  2. Reference existing primitives (var(--brand-500)) rather than new raw values; introduce a new palette ramp only when no existing hue fits, and define it in OKLCH.
  3. If you rename a token, alias the old name for one minor cycle (see MATURITY).
  4. Document it (token card and/or README token index). Validate contrast for any text/border colour.

Add a pattern​

A pattern is a composition (a workflow, a form layout, a permission flow). Build it from existing components; if you find yourself writing one-off markup twice, promote it to a component first. Document the recipe in PATTERNS.md (or the relevant docs/ guide) with a @dsCard if it warrants a visual.

Add a product signature​

Signatures live in tokens/signatures.css and re-skin a subtree via data-signature="…".

  1. Add a canonical hue to the --domain-* set in colors.css.
  2. Add [data-signature="<name>"] { --sig: var(--domain-<name>); } — the shared [data-signature] block derives the rest and adapts to light/dark automatically.
  3. If the hue is light (e.g. amber), override --accent-on to a dark value so on-accent text passes contrast.
  4. Note the recommended data-density in a comment and add the signature to the signatures card.

Add a template​

Templates are starting folders consumers copy. Create templates/<slug>/<Slug>.dc.html via dc_write with <!-- @template name="…" description="…" --> as the first line of the body and <helmet><script src="./ds-base.js"></script></helmet>. Keep every file the template needs inside templates/<slug>/.

Demo data & assets​

  • Real photos in kits are reference-only (Pexels), declared in assets/demo/ and excluded from the package. Never depend on them in a shipped component.
  • Prefer CSS gradient/placeholder fallbacks so a component looks intentional even if an image 404s.

Review expectations​

  • Passes all applicable QA gates.
  • Tokens-only styling; correct maturity status; docs updated.
  • check_design_system clean.
  • Semver-appropriate (see MATURITY); breaking changes carry a migration note.