quantumcss

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Quick Reference

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

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY:
    git pull --rebase
    bd sync
    git push
    git status  # MUST show "up to date with origin"
    
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES:


Beads Workflow Integration

This project uses beads_viewer for issue tracking. Issues are stored in .beads/ and tracked in git.

Essential Commands

# 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

Workflow Pattern

  1. Start: Run bd ready to find actionable work
  2. Claim: Use bd update <id> --status=in_progress
  3. Work: Implement the task
  4. Complete: Use bd close <id>
  5. Sync: Always run bd sync at session end

Key Concepts

Session Protocol

Before 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

Best Practices


CSS Architecture: Static-First

The 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.

Ownership Rules

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

Decision Rules

  1. Named UI components (buttons, cards, shells, dialogs, search, starlight widgets, layout presets) → define the full class in quantum-components.css only.
  2. Atomic utilities (flex, p-4, text-sm, gap-2) → quantum-utilities.css only.
  3. Never define the same class in two static files. Utilities layer loads last and wins cascade conflicts.
  4. Do not reintroduce content-scan JIT into scripts/build.js. Refresh utilities with npm run emit:utils only when the catalog sources change, then prefer hand-edits to the CSS.
  5. Theming is CSS variables — kitchen-sink Theme Designer and quantum.config.json only change tokens, not class collection.

Build Pipeline

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

Legacy bridge (maintainers only)

Example HTML

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.


Making a Release

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

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

  1. File issues for remaining work - Create issues for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. PUSH TO REMOTE - This is MANDATORY:
    git pull --rebase
    bd dolt push
    git push
    git status  # MUST show "up to date with origin"
    
  5. Clean up - Clear stashes, prune remote branches
  6. Verify - All changes committed AND pushed
  7. Hand off - Provide context for next session

CRITICAL RULES: