Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (62 loc) · 3.14 KB

CONTRIBUTING.md

File metadata and controls

80 lines (62 loc) · 3.14 KB
Raw

Contributing to SLASHED

Conventions below are enforced by stylelint, tests, and git hooks.

Setup

npm ci                 # install dev tooling
npm run test:install   # one-time: install the Chromium test browser

There is no build step for consumers — scripts/bundle.js concatenates core/

  • optional/ into dist/ bundles for maintainers.

Workflow

npm run build        # rebuild dist/ bundles
npm run watch        # rebuild on change
npm run lint:css     # stylelint (must pass)
npm run lint:css:fix # auto-fix
npm test             # Playwright regression suite (light + dark)
npm run docs:tokens  # regenerate docs/tokens.md from source

Before opening a PR: npm run lint:css && npm run build && npm test must pass, and dist/ must be rebuilt and committed.

Conventions (enforced)

  • Custom properties start with --sf-; keyframes start with sf-.
  • Tokens, not literals. Every value in base/layout/components/etc. goes through var(--sf-*). Colours use oklch() with relative colour syntax for derived values.
  • Layers. Every rule lives in its @layer (see core/layers.css). Keep selectors low-specificity (single class, element, :root).
  • .sf-is-* is reserved for runtime state classes (the slashed.states layer) — never utilities or variants.
  • Public vs internal tokens. Label new tokens in the file header (PUBLIC / PUBLIC-ADVANCED / INTERNAL). Keep alias chains ≤2 indirections (3 nodes max); no duplicate/dangling/cyclic aliases.
  • Scope of base. Global base covers flow/inline text only. Rich blocks belong in .sf-prose; widgets and form controls are opt-in/component territory (see architecture.md).

Tests & demo coverage

  • Any new .sf-* or .sf-is-* class in core/*.css must appear in demo/index.html (tests/coverage.test.js).
  • Any new token must resolve in both themes (tests/tokens.spec.js); tokens whose value is inherit go in that file's EXPECTED_EMPTY allowlist.
  • Add a focused assertion when you fix a bug.

Commits

Follow Conventional Commits — commitlint runs via git hooks. CHANGELOG.md follows Keep a Changelog.

Releasing

CHANGELOG.md is maintained by hand; the release pipeline reads the matching ## [x.y.z] section.

  1. Move accumulated ## [Unreleased] entries under a new ## [x.y.z] - YYYY-MM-DD heading; leave a fresh empty ## [Unreleased].
  2. Run npm run release (patch), npm run release:minor, or npm run release:major. This bumps package.json, runs scripts/version-sync.js (propagates the version to docs/roadmap.md, docs/llm-guide.md, and the configurator package files), rebuilds bundles, commits, tags, and pushes.
  3. The pushed tag triggers release.yml (GitHub Release + dist assets) and re-aligns version references on main. The dist branch is published by publish-dist.yml on every push to main.

Scope

SLASHED rejects some additions (utility-class proliferation, a 7th brand colour, pre-compiled themes, decorative token bloat). Open an issue first for sizeable features.