| name | beamcss-project |
| description | Use when working in the Beam CSS repository, including planning, implementing, reviewing, or testing changes to the Rust core/compiler, CLI, Node package, Vite/PostCSS/MCP integrations, grammar, JSON5 config parsing, native binding, examples, snapshots, and project workflow. |
Beam CSS Project
Start Here
Read CLAUDE.md before changing code and treat it as the source of truth for project architecture, commands, non-negotiables, out-of-bounds areas, and the per-slice workflow.
Use this skill to keep Beam CSS changes small, readable, and aligned with the repo's public API and supply-chain constraints.
Code Style
- Keep files single-purpose. For new or actively refactored modules, aim for 200-250 lines unless a local pattern strongly justifies more.
- Split large legacy files only when the split directly supports the current change. Do not perform drive-by module churn.
- Prefer clear Rust and TypeScript modules with small, focused functions and explicit data flow.
- Write code a junior developer can step into and understand without hidden cleverness.
- Use existing repo patterns before introducing new abstractions.
- Keep comments concise. Prefer one-line, all-caps intent comments only when the code's reason is not obvious.
Beam Constraints
- Treat the class-string grammar as public API. Any grammar change needs semver-level care and must be reflected in
docs/beam-css-spec.md when appropriate.
- Preserve the JSON5-only config parsing contract. Do not execute TypeScript config files.
- Keep the napi-rs interface in
crates/beam_node/src/lib.rs and packages/beamcss/src/native.ts in sync whenever either side changes.
- Preserve the fixed layer order:
beam.reset, beam.tokens, beam.base, beam.utilities.
- Do not add Rust crates, top-level npm packages, postinstall scripts, or CI changes without explicit approval.
- Use every completed grammar feature in
examples/.
- Add or update golden-file snapshots for compiler output changes.
- After
beam_core or beam_node changes, rebuild the committed native binding before relying on JS/plugin tests that load it.
Slice Workflow
Before code changes, state the slice contract:
- Intended slice
- Allowed files/functions
- Tests that must pass
- Explicit non-goals
After the slice, emit the receipt from CLAUDE.md:
- Intended slice
- Allowed files/functions
- Actual files/functions changed
- Behavior added
- Behavior removed
- Tests added/updated
- Explicit non-goals
- Rollback path
Then run the two gates in order:
- Authorization gate: confirm actual changes match the allowed files/functions.
- Quality gate: confirm the implementation is correct, readable, and covered by the selected tests.
