@marschildox/codeready-ds
v0.6.1
Published
Code-first design system — React components, design tokens, and multi-brand theming
Readme
@marschildox/codeready-ds
React component library with design tokens and multi-brand theming, built on Base UI.
Contributor and maintainer documentation lives in
docs/README.md. This README is consumer-facing (install + usage); the docs directory carries the architecture, registry semantics, and authoring workflow.
Install
npm install @marschildox/codeready-ds @base-ui-components/react react react-domImport
// styles must be imported before base
import '@marschildox/codeready-ds/styles'
import '@marschildox/codeready-ds/base'
import { Button, Input, Select, RadioGroup } from '@marschildox/codeready-ds'
import { HeroLeadForm, type FormField, type NavItem } from '@marschildox/codeready-ds/sections'
import { BRANDS } from '@marschildox/codeready-ds/brands'
// ./types is for tooling that reads DS registry metadata — not needed for product-app component usage
import type { ComponentMeta, ComponentRegistry } from '@marschildox/codeready-ds/types'Component prop types (
FormField,NavItem,ContactMethod, etc.) are exported from the entrypoint that owns the component. Import them from@marschildox/codeready-ds(UI primitives) or/sections(page sections), not/types.
Setup
1. Load styles
Import both stylesheets — in this order — in your root layout:
import '@marschildox/codeready-ds/styles'
import '@marschildox/codeready-ds/base'/styles— design tokens as CSS custom properties on:root. No element styles applied./base— applies tokens tobody, headings, and form controls. Includes a minimal reset.
/styles must come before /base.
2. Set brand and theme
Add data-brand and data-theme to <html>:
<html data-brand="brand-default" data-theme="light">Supported values:
| Attribute | Values |
|-----------|--------|
| data-brand | brand-default, gubernamental |
| data-theme | light, dark |
3. Load fonts
The package ships token values (--font-title: 'Inter', --font-body: 'Roboto') but does not load font files. You must load them.
Option A — Google Fonts
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Roboto:wght@400;500;700&display=swap"
rel="stylesheet"
/>Option B — Fontsource (self-hosted)
npm install @fontsource/inter @fontsource/robotoimport '@fontsource/inter/400.css'
import '@fontsource/inter/500.css'
import '@fontsource/inter/600.css'
import '@fontsource/inter/700.css'
import '@fontsource/roboto/400.css'
import '@fontsource/roboto/500.css'
import '@fontsource/roboto/700.css'Vite / Astro SSR config
@base-ui-components/react must be bundled through Vite in SSR mode:
// vite.config.js or astro.config.mjs
export default defineConfig({
vite: {
ssr: {
noExternal: ['@base-ui-components/react']
}
}
})Troubleshooting
| Symptom | Cause | Fix |
|---------|-------|-----|
| Serif body font (Times/Georgia) | /base not imported | Add import '@marschildox/codeready-ds/base' |
| System sans-serif instead of Inter/Roboto | Font files not loaded | Add Google Fonts or Fontsource imports |
| Token variables undefined | /styles not imported | Import /styles before /base |
| SSR build error for Base UI | Missing noExternal | Add noExternal: ['@base-ui-components/react'] |
Release process
How publishing works
This package uses npm Trusted Publishing — no long-lived npm token is stored anywhere. Publishing is fully OIDC-based.
When a v*.*.* tag is pushed, the GitHub Actions workflow (.github/workflows/publish.yml):
- Runs inside the
npm-publishGitHub environment (tag-restricted, no secrets stored). - Requests a short-lived OIDC identity token from GitHub (
id-token: write). - Builds the compiled package (
pkg/) viatsc+ CSS copy, then validates brands and sections. - Calls
npm publish --access public --provenance. The npm CLI automatically exchanges the GitHub OIDC token for a temporary publish credential — noNPM_TOKENrequired. - Attaches a Sigstore provenance attestation to the published package. The attestation cryptographically links the tarball to the exact commit, run ID, and workflow file.
Consumers can verify the attestation at any time:
npm audit signatures @marschildox/codeready-dsCutting a release
# 1. Validate and pack locally
npm run release -- <version>
# e.g. npm run release -- 0.4.0
# 2. Inspect the tarball — only pkg/ paths should appear
tar -tzf /tmp/marschildox-codeready-ds-<version>.tgz | head -30
# 3. Commit the version bump and changelog
git add package.json CHANGELOG.md
git commit -m "chore: release v<version>"
# 4. Tag and push — this triggers the publish workflow
git tag v<version>
git push && git push --tagsCI builds, validates, and publishes automatically. No manual npm interaction needed.
One-time setup — GitHub side
- In the repository, go to Settings → Environments → New environment.
- Name it
npm-publish. - Under Deployment branches and tags, restrict to tag pattern
v*.*.*. - No secrets required — Trusted Publishing uses OIDC; there is no npm token to store.
One-time setup — npm side
Complete these steps after the first manual publish (below) creates the package on npm.
Go to npmjs.com → your package
@marschildox/codeready-ds→ Settings.Confirm Package visibility is Public.
Under Publish access → Trusted Publishers, click Add a trusted publisher.
Enter exactly:
| Field | Value | |-------|-------| | Publisher | GitHub Actions | | Repository owner |
marschildox| | Repository name |codeready-ds| | Workflow filename |publish.yml| | Environment |npm-publish|
Once saved, GitHub Actions can publish this package using only its OIDC identity — no npm account credentials required.
First publish (manual, one-time only)
The package must exist on npm before Trusted Publishing can be configured. Use --otp once:
npm run build:pkg
npm publish --access public --otp=<6-digit-code>After that, configure the Trusted Publisher on npm as described above. All subsequent releases go through CI with no token.
Consumer repo — after a release
npm install @marschildox/codeready-ds@latestNo consumer-side changes are needed between patch/minor releases. For major releases, check the CHANGELOG for breaking changes.
For component authoring, registry structure, and LLM-assisted workflows see docs/component-authoring-workflow.md.