Semanticus CSS

Appearance

Contributing ​

Thank you for considering contributing to Semanticus CSS!

Semanticus CSS is the sum of all the work done by Pico CSS and Bootstrap's original author(s) and the contributions, plus the work of the author and maintainer of this project.

Hopefully this will change and your name gets added to the list of contributors as well.

The roadmap, bug fixes and keeping up to date with new emerging patterns is a daunting task for one person alone and I'd love for you to be part of shaping the future of this project.

When contributing, please keep the Core Principles in mind.

Code Guidelines ​

Adding New Features ​

  1. Semantic component → add src/semantics/_<element>.css and import it in src/semantics/modules.css
  2. Utility class → add to the appropriate src/utilities/<category>/_<file>.css
  3. Variant class → add to src/variants/_<file>.css and import in src/variants/modules.css
  4. Palette → add src/palettes/<name>.css and register it in scripts/build-palettes.js
  5. Size → add src/sizes/<name>.css and register it in scripts/build-sizes.js

Code Style ​

  • Follow the existing CSS conventions — see Token Conventions for the naming rules applied to CSS custom properties

  • Use CSS custom properties (--*) for theming rather than hard-coded values

  • Before submitting:

    • Run the linter:
    bash
    npm run lint
    • and the visual regression tests if your change affects styles:
    bash
    npm test

Documentation ​

If your contribution is user-facing, please update the documentation:

  • Update relevant guides in docs/
  • Include examples showing semantic HTML usage
  • Explain any accessibility considerations
  • Document CSS variables that can be customized

How to setup the project ​

  • Install Node.js (v18 or higher recommended) if you haven't already.

  • Clone the repository

bash
git clone https://github.com/semanticus/semanticus-css.git
  • Move into the project directory
bash
cd semanticus-css
  • Install dependencies
bash
npm install

Development ​

Make sure to build the project before running the development servers:

bash
npm run build
  • Scenario 1: Changes to the *.css files in the src directory

Launch storybook at http://localhost:6006 by running:

bash
npm run storybook
  • Scenario 2: Changes to the *.md files in the docs/ directory

Launch vitepress at http://localhost:5173 by running:

bash
npm run docs:dev

In both scenarios, you will probably want add or update the existing *.demo.ts files in the demos/ directory that contain the HTML examples used both by storybook and vitepress.

Testing ​

Semanticus CSS uses Playwright for visual regression testing.

Before the first local test run, install the configured Chromium browser and build the CSS:

bash
npx playwright install chromium
npm run build
npm test

Repeat the browser installation after upgrading Playwright. The dev container already includes the matching browsers. Subsequent local runs only need npm test after rebuilding any CSS changes.

If browser installation reaches 100% and then stalls during extraction on Node 26 or Node 24.16+, check that dependencies are up to date with npm ci. Playwright 1.60.0 fixes the archive extraction hang present in 1.59.1.

To run a specific test:

bash
npm test <path to the spec.ts file>

When writing new tests, or when you want to debug existing ones:

bash
npm run test:dev

Snapshot consistency and the dev container ​

Playwright's pixel-level snapshots are sensitive to the OS and browser rendering engine. To ensure that snapshots are always generated in the same environment as CI, this project ships a dev container (.devcontainer/devcontainer.json) based on the official Playwright Docker image (mcr.microsoft.com/playwright:v1.60.0-noble, Ubuntu 24.04).

Generate and update Linux snapshots inside the dev container or CI's matching Playwright container. Snapshot paths include the operating system: macOS and Windows baselines can be kept separately, but they do not replace the Linux baselines required by CI. Include Linux baselines when adding a new visual test.

To generate baselines through CI, run the CI checks workflow on the branch containing the new tests and enable Regenerate visual snapshots. Download the playwright-snapshots artifact, review the generated Linux images, and commit the changes under tests/_snapshots/chromium/linux/. Normal CI runs continue to compare against committed baselines; regeneration only runs when explicitly requested.

Opening the dev container ​

  1. Install the Dev Containers extension in VS Code.
  2. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and run Dev Containers: Reopen in Container.
  3. VS Code will build the container and run npm ci automatically.

Before opening a PR ​

If your changes affect any styles, run the full test suite inside the dev container and commit any snapshot changes:

bash
# Run the tests — this will flag any visual regressions
npm test

# If the visual changes are intentional, update the snapshots
npm run test:update-snapshots

Commit the updated tests/_snapshots/ files alongside your other changes. PRs that introduce style changes without updated snapshots will fail CI.