SLASHED

CLAUDE.md

Current version: 0.6.30.0 (pre-1.0).

See CONTRIBUTING.md for repo layout, gotchas, build commands, and versioning. See ROADMAP.md for pending work.

Frozen philosophy & version ceiling

The philosophy is frozen. See PHILOSOPHY.md — the immutable constitution. Every change is evaluated against the seven pillars. CI enforces compliance via bin/check-philosophy-drift.sh.

The version is frozen at 0.6.x.x. Token & variable system must be finished, tested, and DX-validated before 0.7.0.0. See docs/VERSION-FREEZE.md for unlock conditions. bin/bump-version.sh rejects ≥ 0.7.0.0 without FREEZE_UNLOCK.

Run bin/sync-docs.sh to verify all documentation, tokens, and integrity checks pass in one command.

Framework philosophy — evaluate every change against these

SLASHED = Standalone · Lean · Agnostic · Structured · Hybrid · Edgeless · Deterministic.

BEM-first authoring. Everything is written in BEM — this is the methodology, not a component library. The shipped .sf-* components are an opt-in convenience layer: they pre-bake the most common patterns (buttons, cards, forms, …) so the consumer doesn’t re-author them, but they are not part of the essential bundle (slashed-essential.css ships only tokens + core — the frozen source-of-truth surface; slashed-full.css is the everything bundle including utilities, components, visual utilities, animations, and viewport utilities). They are not “the way” to use the framework. The consumer can ignore them entirely and author their own unique BEM blocks (e.g. .product-card, .site-header) styled with framework tokens (var(--sf-space-m), var(--sf-color-surface), var(--sf-radius-m), …). Both paths are equally idiomatic. The naming rules (__, --, no element-in-element, kebab-case) apply identically in both cases. Layout primitives wrap BEM blocks to compose pages. Utilities are subordinate helpers — reach for them only for layout tweaks and one-off adjustments where authoring a BEM class would be overkill. If a pattern repeats, it becomes a BEM block, not a stack of utilities.

Mobile-first responsive model. All breakpoint prefixes (sm:, md:, lg:, xl:) use min-width — styles apply at the named breakpoint and up. Write the mobile layout first, then layer in breakpoint overrides. Responsive design in SLASHED has three layers, in order of preference: (1) fluid tokens — --space-*, --text-*, and --leading-* tokens use clamp() and scale continuously with the viewport; reach for them first and you need no @media rule at all. (2) container-aware primitives — .grid, .stack, .cluster, and other layout primitives respond to their own container width via @container, not the viewport; they handle most structural layout automatically. (3) breakpoint utilities — sm:, md:, lg:, xl: prefix classes handle the remaining discrete viewport-level switches (show/hide a nav, flip a flex direction, change column count). Reach for (3) only when (1) and (2) are not sufficient.

Standalone — No build step, no Node, no npm, no runtime dependencies. The consumer links a CSS file. Any change that introduces a preprocessor, build tool, or runtime dependency on the consumer side is permanently out of scope.

Lean — Every class earns its place. Additions are at the maintainer’s discretion. Does it earn its bytes? Is it composable from existing classes? Decorative utilities belong in slashed-utilities-visual.css, not core.

Agnostic — Works on any platform that can load a CSS file. Framework integrations (Bricks, WordPress) are additive and opt-in, never a dependency.

Structured — Cascade layers enforce specificity order. BEM is the canonical naming scheme — .block__element--modifier, with .sf-* reserved for framework blocks; see CONTRIBUTING.md → “Authoring order and BEM naming” for the full rules. Token hierarchy is explicit. New components follow the same layer, naming, and token conventions as existing ones.

Hybrid — Three authoring layers in a fixed hierarchy: BEM is the default authoring style for everything (framework .sf-* components and consumer-authored blocks alike); layout primitives wrap BEM blocks to compose pages; utilities patch the gaps. Two interactivity paths (pure-CSS baseline + optional JS enhancements). Every interactive component must ship a meaningful pure-CSS path first. HTML-first: reach for <details>, <dialog>, :has(), and native form elements before writing JavaScript.

Edgeless — The framework never blocks the consumer. Unlayered BEM always beats framework layers — no !important needed. Instance tokens allow single-line component modifications. If a consumer needs !important to override something, that is a framework bug.

Deterministic — Tokens drive the system. A given token input always produces the same output. New tokens must follow existing derivation patterns (color-mix(), light-dark(), clamp()). Magic numbers in framework CSS are bugs — every value a consumer might want to change must be a custom property.

Mandatory actions

For every framework-surface change (new/renamed/removed class, token, or JS API):

When implementing any item tracked in ROADMAP.md:

At every version bump:

Before submitting any PR:

Critical gotchas

This site is open source. Improve this page.