This project uses bd (beads) for issue tracking. Run bd onboard to get started.
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --status in_progress # Claim work
bd close <id> # Complete work
bd sync # Sync with git
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
git pull --rebase
bd sync
git push
git status # MUST show "up to date with origin"
CRITICAL RULES:
git push succeedsThis project uses beads_viewer for issue tracking. Issues are stored in .beads/ and tracked in git.
# View issues (launches TUI - avoid in automated sessions)
bv
# CLI commands for agents (use these instead)
bd ready # Show issues ready to work (no blockers)
bd list --status=open # All open issues
bd show <id> # Full issue details with dependencies
bd create --title="..." --type=task --priority=2
bd update <id> --status=in_progress
bd close <id> --reason="Completed"
bd close <id1> <id2> # Close multiple issues at once
bd sync # Commit and push changes
bd ready to find actionable workbd update <id> --status=in_progressbd close <id>bd sync at session endbd ready shows only unblocked work.bd dep add <issue> <depends-on> to add dependenciesBefore ending any session, run this checklist:
git status # Check what changed
git add <files> # Stage code changes
bd sync # Commit beads changes
git commit -m "..." # Commit code
bd sync # Commit any new beads changes
git push # Push to remote
bd ready at session start to find available workbd create when you discover tasksbd sync before ending sessionThe product ships only static CSS. There is no content-scan JIT in npm run build.
Tree-shaking class collection is gone — maintain finite static catalogs instead.
| Layer | File | Owns |
|---|---|---|
| Tokens | src/styles/quantum-base.css |
All --q-* design tokens (:root only) |
| Icons | src/styles/quantum-icons.css |
Icon mask utilities |
| Components | src/styles/quantum-components.css |
Named UI (layout + decoration for that component) |
| Animations | src/styles/quantum-animations.css |
@keyframes and .ani-* |
| Utilities | src/styles/quantum-utilities.css |
Finite atomic utility catalog only |
| Theme overlay | quantumcss theme / kitchen-sink knobs |
Optional --q-* overrides only |
quantum-components.css only.flex, p-4, text-sm, gap-2) → quantum-utilities.css only.scripts/build.js. Refresh utilities with npm run emit:utils only when the catalog sources change, then prefer hand-edits to the CSS.quantum.config.json only change tokens, not class collection.quantum-base.css → quantum-icons.css → quantum-components.css → quantum-animations.css → quantum-utilities.css
npm run build # static concat + minify → dist/quantum.min.css
npm run emit:utils # maintainer: rebuild quantum-utilities.css from defaults + example class inventory
npm run theme # optional: theme-overlay.css from quantum.config.json
src/defaults.js + src/generator.js remain as emit inputs for scripts/emit-static-utilities.js.src/styles/component-owned-classes.json. Emit excludes them so they cannot reappear in quantum-utilities.css.All example files should load only dist/quantum.min.css (which includes everything). Never load source CSS files (src/styles/*.css) alongside the built output — that double-applies rules and creates cascade bugs.
npm run release only refreshes release metadata (README badge, portfolio timeline, examples/index version). It does not bump package.json, build dist, or create git tags. The build banner already reads version from package.json.
# 1. Bump version in package.json (semver: patch, minor, major)
vim package.json # Update "version" field
# 2. Build the CSS you intend to ship
npm run build
# 3. Refresh release metadata (badge, portfolio timeline, index version)
npm run release
# 4. Verify portfolio.html timeline entry; edit the description if it's generic
git log --oneline -20
# 5. Commit metadata + dist (and any other release files)
git add package.json README.md examples/portfolio.html examples/index.html dist
git commit -m "release: vX.Y.Z — <summary>"
# 6. Tag and push
git tag vX.Y.Z
git push && git push --tags
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO listsbd prime for detailed command reference and session close protocolbd remember for persistent knowledge — do NOT use MEMORY.md filesWhen ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.
MANDATORY WORKFLOW:
git pull --rebase
bd dolt push
git push
git status # MUST show "up to date with origin"
CRITICAL RULES:
git push succeeds