strata
DocsPackagesBlogsShowcase

Contributing to Strata CSS

Thank you for your interest in contributing. Strata is open source and welcomes contributions of all kinds — bug fixes, new components, utility classes, documentation improvements, or performance work.

Versioning Rules

Strata uses a modified semantic versioning scheme: MAJOR.FEATURE.BUGFIX

What each number means

1 . 2 . 6
│   │   └── Cumulative bugs fixed since this MAJOR era began
│   └─────── Cumulative feature releases since this MAJOR era began
└─────────── Design era — changes only on fundamental redesign

MAJOR — era change (resets FEATURE and BUGFIX to 0)

Bumped only when something changes that requires every user to manually update their codebase. Examples:

  • CSS layer structure renamed or reordered
  • Core design tokens renamed (e.g. --st-primary → --st-brand)
  • Scanner or build API breaking changes
  • Class naming convention changed

When MAJOR bumps, all packages (@strata-packages/forms, @strata-packages/picker etc.) also release a new MAJOR build even if their own code is unchanged — the MAJOR bump is the compatibility contract.

A MIGRATION.md file is required before any MAJOR release ships. No migration doc = no MAJOR bump.

FEATURE — new capabilities (never resets within a MAJOR era)

Bumped once per release that ships new functionality:

  • New utility classes or component classes
  • New options on existing APIs
  • New packages (@strata-packages/picker etc.)
  • New CSS variables or tokens

Never resets between FEATURE releases in the same era. 1.5.x means 5 feature releases have shipped in era 1.

BUGFIX — cumulative quality count (never resets within a MAJOR era)

Bumped once per bug fixed. Never resets mid-era.

1.3.6 means: era 1, 3 feature releases, 6 total bugs fixed. The BUGFIX number tells you the quality history at a glance.

Examples

1.0.0   Initial release of era 1
1.1.0   First feature set shipped (BUGFIX stays at 0)
1.1.1   Bug fixed (total bugs this era: 1)
1.1.2   Another bug fixed (total: 2)
1.2.2   New features shipped (FEATURE → 2, BUGFIX stays at 2)
1.2.3   Bug fixed (total: 3)
1.3.3   More features (FEATURE → 3, BUGFIX stays at 3)
2.0.0   Major redesign — both counters reset
2.1.0   First features in era 2

Pre-release Tags

Only beta and main are published to npm. dev and test are internal integration/QA stages — code there is never released.

Branch Version format npm tag GitHub label
dev — not published —
test — not published —
beta 1.2.3-beta.1 --tag beta Pre-release
main 1.2.3 --tag latest Latest release

Users install specific stages:

npm install strata-css          # stable (latest)
npm install strata-css@beta     # beta

Package Versioning Policy

Each package (@strata-packages/forms, @strata-packages/picker etc.) versions independently between MAJOR releases:

strata-css          1.1.0  →  1.2.0  →  1.3.6
@strata-packages/forms   1.0.0  →  1.1.3  →  (unchanged)
@strata-packages/picker  1.0.0  →           →  1.1.0

Packages only move when they have their own changes. They do not bump just because core bumped a FEATURE or BUGFIX version.

Exception — MAJOR bumps: When strata-css releases 2.0.0, every package releases a 2.0.0 build (even if unchanged) to update the peer dependency range:

"peerDependencies": {
  "strata-css": ">=1.0.0 <2.0.0"
}

This range is the compatibility contract — any 1.x.x package works with any 1.x.x core.

Branch Pipeline

Only four branches exist, ever: main, beta, test, dev. No feature/*, fix/*, or other short-lived branches — work commits directly onto dev. Never push directly to main, beta, or test.

dev → test → beta → main

Rules

  1. Work is committed directly to dev — build must pass
  2. PR dev → test — run build verify
  3. PR test → beta — final check before release
  4. PR beta → main — requires review
  5. After merge to main: tag the version and publish to npm

Build check at each stage

node bin/strata.js --build

Commit Message Format

Commit prefix drives which number bumps:

Prefix Version impact Example
feat: FEATURE++ feat(select): add autoWidth option
fix: BUGFIX++ fix(picker): correct scroll offset
docs: none docs: update CONTRIBUTING.md
refactor: none refactor(registry): simplify spacing loop
test: none test: add picker debug example
chore: none chore: update dependencies
BREAKING: MAJOR++ BREAKING: rename --st-primary tokens

Publishing Checklist

Before publishing to npm:

  • package.json version updated correctly under MAJOR.FEATURE.BUGFIX rules
  • CHANGELOG.md entry written
  • Build passes on all branches in pipeline order
  • PR merged to main
  • Git tag created: git tag v1.2.3 && git push origin v1.2.3
  • npm publish --tag latest (stable) or --tag beta (pre-release)

For MAJOR releases, additionally:

  • MIGRATION.md written and committed
  • All packages have MAJOR.0.0 builds ready
  • Deprecation notice shipped in previous MINOR release