SLASHED

SLASHED Philosophy

FROZEN. This document is the project constitution. Code serves it, not the reverse. Any modification requires a philosophy-amendment issue + maintainer sign-off + 30-day cooling period.

---

The Acronym

Standalone · Lean · Agnostic · Structured · Hybrid · Edgeless · Deterministic

Each letter is a non-negotiable design constraint. Where CSS imposes physical limitations, the pragmatic workaround is documented — not hidden.

---

The Seven Pillars

1. Standalone

One <link> tag. No build step. No dependencies. No CLI. No configuration.

• Can you use it by adding one <link> to a static HTML file? → YES.
• Does anything require Node, npm, or any build tool? → NO.

2. Lean

Every byte ships with purpose. Small, fast, signal-dense.

The essential bundle (tokens + core) is the framework’s frozen source-of-truth surface — design tokens plus reset, base elements, layout primitives, a11y and print. Everything needed to author BEM blocks against the design system. Utilities, components, decorative helpers, animations and viewport breakpoints ship as optional addons and travel together in slashed-full.css. Utilities support BEM, not replace it — decoration lives in optional addons.

• Does the addition earn its bytes? → Must justify itself.
• Can it be achieved with existing tokens/classes? → Don’t add.
• Is it decoration? → Optional addon, never essential.

3. Agnostic

Works on any platform that can serve a CSS file. The essential bundle assumes nothing about your stack. Integration layers are separate opt-in files — companions, never requirements.

• Does it assume a specific engine or framework? → Reject.
• Does it work in a static .html opened from the filesystem? → YES.
• Platform-specific code in essential? → Bug.

4. Structured

Visible, predictable architecture.

Layers enforce specificity: reset → base → layout → components → utilities → visual → animations → a11y → overrides

BEM is the methodology: .block__element--modifier. No element-in-element. No camelCase. No arbitrary names.

Tokens in three tiers:

1. Primitives — raw scale values (--sf-space-m, --sf-radius-l)
2. Semantic aliases — role-based names (--sf-color-bg, --sf-color-border)
3. Instance tokens — per-component knobs (--sf-card-padding, --sf-btn-bg)

5. Hybrid

Multiple methodologies work together, not against each other.

1. BEM blocks — the default. Scoped, reusable UI.
2. Layout primitives — wrap blocks to compose pages.
3. Utilities — patch the gaps. If a pattern repeats, promote to a block.

CSS renders. JavaScript enhances. Both first-class, neither dependent on the other.

6. Edgeless

The framework gets out of your way. Conventions and guardrails, but no walls.

• Your unlayered CSS always wins over framework layers — no !important needed.
• Instance tokens override inline: style="--sf-card-padding: 2rem".
• slashed.overrides layer is empty by design — your escape hatch.
• Load only what you need. Ignore the rest.

If a developer reaches for !important to override the framework — that’s a framework bug.

7. Deterministic

Same inputs → same outputs. Predictable, auditable, no surprises.

• Tokens are the single source of truth for every visual decision.
• Every changeable value is a custom property.
• Derivation patterns are consistent across the system.
• Magic numbers are bugs.
• Re-theme the entire system from :root overrides alone.

---

Permanent Decisions

Decision	Rationale
No Sass / Less / PostCSS	Buildless is a feature
No JIT / class scanning	Same reason
No JS component framework	SLASHED is CSS. HTML-first.
No paid tier	MIT, all features, forever
No 21-shade color scale	11 stops + alpha variants suffice
Layer order is frozen	9-layer stack is the architecture
BEM naming is mandatory	No alternative convention
Mobile-first is the default	min-width breakpoints, optimized path

---

DX Contract

1. Predictable naming — know one token, guess the rest.
2. Discoverable — everything in cheatsheet.html.
3. Composable — tokens work in any property context.
4. Consistent scales — t-shirt sizes (2xs → 3xl); numeric only for sequences.
5. Category parity — every category a modern dev expects is covered. Gaps = bugs. Depth is lean by design.

---

Bundle Hierarchy

File	Role	Optionality
Essential (tokens + core)	The framework’s frozen source-of-truth surface. BEM authoring foundation.	Required.
Utilities	Layout, spacing and typography utility classes. Support BEM, never replace it.	Optional.
Components	Pre-baked .sf-* UI blocks.	Optional.
Animations	Transition/animation helpers.	Optional.
Viewport utilities	Breakpoint-prefixed classes (sm:, md:, lg:, xl:).	Most optional.
Visual utilities	Decorative classes. Tailwind/Bootstrap most-used-class parity.	Most optional.
Full (slashed-full.css)	Essential + every optional addon bundled into a single <link>.	One-link convenience.
Experimental	Bleeding-edge CSS without full browser support.	Most optional.

---

Enforcement

1. bin/check-philosophy-drift.sh — automated violation scanner.
2. .github/workflows/philosophy-guard.yml — CI blocks merge on violation.
3. Pre-commit hooks — catches drift locally.
4. Code review — every PR evaluated against the pillars.
5. This document — final authority. Code conflicts = code is wrong.

---

SLASHED is opinionated by design. These opinions are the product.

This site is open source. Improve this page.