docs: add user-manual with end-user color system guide

[jackgranatowski]

Starts a new end-user documentation tree (distinct from the
contributor-facing docs/) with a task-oriented guide to the color
system: source tokens, light/dark, shade ramps, status colors, and
text-on-color contrast, verified against core/tokens.css and
core/themes.css.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01UqerHc5MPryMBp62TVS1Ds

[coderabbitai]

Warning

Review limit reached

@jackgranatowski, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 51 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c9b956a0-7c67-4186-9222-36f37757ce12

📥 Commits

Reviewing files that changed from the base of the PR and between b922cc0 and 55a7b93.

📒 Files selected for processing (2)

• user-manual/README.md
• user-manual/colors.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/slashed-color-system-cdzye4

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Add end-user user-manual with color system guide

📝 Documentation 🕐 20-40 Minutes

AI Description

• Introduce a new end-user documentation tree under user-manual/, separate from contributor docs.
• Add a task-oriented color system guide covering tokens, ramps, status colors, and contrast.
• Cross-reference canonical sources (core/tokens.css, core/themes.css) and existing docs pages.

Diagram

graph TD
U(["End user"]) --> R["user-manual/README.md"] --> C["user-manual/colors.md"] --> T["core/tokens.css"] --> H["core/themes.css"]
C --> D["docs/theming.md"] --> K["docs/tokens.md"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Place the manual under existing `docs/` (e.g., `docs/user-manual/`)

• ➕ Single documentation root reduces navigation split-brain
• ➕ Simplifies tooling if docs/ is already wired to a site generator
• ➖ Blurs contributor/reference docs with end-user task guides
• ➖ Harder to enforce different tone, structure, and information density

2. Publish docs via a docs site generator (Docusaurus/MkDocs) from the start

• ➕ Built-in navigation, search, versioning, and link checking
• ➕ Easier long-term scaling for a growing manual
• ➖ Adds build/dependency/tooling overhead for a small initial docs set
• ➖ May be premature until information architecture stabilizes

Recommendation: Keep the separate user-manual/ tree as implemented to preserve a clear audience boundary (end-user task guides vs contributor/reference docs). Revisit site-generator adoption once the manual grows beyond a few pages and needs search/navigation automation.

Files changed (2) +245 / -0

Documentation (2) +245 / -0

README.mdAdd end-user manual entrypoint and navigation +16/-0

Add end-user manual entrypoint and navigation

• Introduces 'user-manual/' as a new documentation home aimed at framework users rather than contributors. Adds a short positioning statement and a contents link to the color guide.

user-manual/README.md

colors.mdDocument the SLASHED color system for end users +229/-0

Document the SLASHED color system for end users

• Adds a comprehensive, task-oriented guide describing the 10 source colors, light/dark derivation, shade ramps and aliases, alpha variants, status tokens, and contrast-safe text-on-color tokens. Includes practical CSS/HTML examples and cross-links to canonical reference docs and core token/theme sources.

user-manual/colors.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 6 rules

1. Overbright base example 🐞 Bug ≡ Correctness

Description

user-manual/colors.md suggests setting --sf-color-base-source-light to oklch(0.99 …), which can
cause derived surface levels (bg/raised) to clamp toward white and become visually indistinguishable
in light mode.

Code

user-manual/colors.md[R38-45]

+:root {
+  --sf-color-primary-source-light:   oklch(0.55 0.18 280);
+  --sf-color-secondary-source-light: oklch(0.30 0.04 280);
+  --sf-color-tertiary-source-light:  oklch(0.62 0.15 200);
+  --sf-color-action-source-light:    oklch(0.62 0.16 150);
+  --sf-color-neutral-source-light:   oklch(0.45 0.01 280);
+  --sf-color-base-source-light:      oklch(0.99 0.004 280);
+}

Relevance

⭐⭐⭐ High

Base/surface clamping behavior actively maintained; base ramp + guidance changed recently (PR456)
and docs updated for theming (PR188).

PR-#456
PR-#188

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The manual’s example uses a near-white base (0.99). core/tokens.css explicitly documents that values
near 1.0 cause lighter surface offsets to clamp to white and become indistinguishable, and the
provided optional theme example uses 0.97 instead.

user-manual/colors.md[34-45]
core/tokens.css[19-24]
optional/theme-example.css[10-17]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The rebranding example sets `--sf-color-base-source-light` to `oklch(0.99 …)`, but the framework’s own guidance warns that near-1.0 base values can flatten the derived surface offsets, making `bg/inset/raised` less distinct.

## Issue Context
This is an end-user manual example and will be copy-pasted; it should align with the framework’s recommended ranges.

## Fix Focus Areas
- user-manual/colors.md[34-46]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Source token naming confusion 🐞 Bug ≡ Correctness

Description

The “10 source colors” section says “You set those” but lists resolved tokens like
--sf-color-primary/--sf-color-danger, while the actual user-settable inputs are the
-source-light/-source-dark tokens; this can mislead users into overriding computed tokens and losing
automatic dark-mode derivation.

Code

user-manual/colors.md[R3-24]

+SLASHED's entire color system is generated from **10 source colors**. You set
+those, and everything else — dark mode, hover states, tints, borders, text
+contrast — is derived automatically. You should never need to hand-pick a hex
+value for a hover state or a dark-mode variant.
+
+> Source of truth: `core/tokens.css` and `core/themes.css`. If anything here
+> ever looks out of date, those files win.
+
+## The 10 source colors
+
+| Token | Role | Use it for |
+|---|---|---|
+| `--sf-color-primary` | Brand identity | Hero sections, brand-forward surfaces, marketing CTAs |
+| `--sf-color-secondary` | Supporting brand color (darker, low-chroma by default) | Secondary brand surfaces, footers, dark bands |
+| `--sf-color-tertiary` | Accent brand color | Tags, chart accents, decorative flourishes |
+| `--sf-color-action` | **Default interactive color** | Buttons, links, focus rings, form controls — anything clickable |
+| `--sf-color-neutral` | Desaturated grey | Feeds text, borders, scrollbars — not used directly very often |
+| `--sf-color-base` | Page surface color | Feeds backgrounds (`bg`, `inset`, `raised`) — not used directly very often |
+| `--sf-color-success` | Positive status | Confirmations, success alerts/badges |
+| `--sf-color-warning` | Caution status | Non-blocking warnings |
+| `--sf-color-info` | Neutral/informational status | Informational banners/badges |
+| `--sf-color-danger` | Negative status | Errors, validation failures, destructive actions |

Relevance

⭐⭐⭐ High

Team accepted fixes for misleading token labeling/docs metadata before (token taxonomy correction in
PR339).

PR-#339

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

core/tokens.css defines the theming inputs as --sf-color-*-source-light (and optional
-source-dark) and then defines the resolved --sf-color-* tokens as var() references to those
source tokens; the manual’s intro/table currently labels the resolved tokens as the ones users
“set.”

user-manual/colors.md[3-24]
core/tokens.css[4-12]
core/tokens.css[14-32]
core/tokens.css[88-102]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The manual calls `--sf-color-primary`/etc “source colors” and implies users set them, but the framework’s theming entry points are the `--sf-color-*-source-light` (and optional `-source-dark`) tokens; `--sf-color-*` are derived/resolved outputs.

## Issue Context
The doc later shows `-source-light` overrides, so the main fix is to clarify terminology and/or adjust the table to prevent incorrect theming guidance.

## Fix Focus Areas
- user-manual/colors.md[3-25]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Overbright base example 🐞 Bug ≡ Correctness

user-manual/colors.md suggests setting --sf-color-base-source-light to oklch(0.99 …), which can
cause derived surface levels (bg/raised) to clamp toward white and become visually indistinguishable
in light mode.

Agent Prompt

## Issue description
The rebranding example sets `--sf-color-base-source-light` to `oklch(0.99 …)`, but the framework’s own guidance warns that near-1.0 base values can flatten the derived surface offsets, making `bg/inset/raised` less distinct.

## Issue Context
This is an end-user manual example and will be copy-pasted; it should align with the framework’s recommended ranges.

## Fix Focus Areas
- user-manual/colors.md[34-46]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Source token naming confusion 🐞 Bug ≡ Correctness

The “10 source colors” section says “You set those” but lists resolved tokens like
--sf-color-primary/--sf-color-danger, while the actual user-settable inputs are the
-source-light/-source-dark tokens; this can mislead users into overriding computed tokens and losing
automatic dark-mode derivation.

Agent Prompt

## Issue description
The manual calls `--sf-color-primary`/etc “source colors” and implies users set them, but the framework’s theming entry points are the `--sf-color-*-source-light` (and optional `-source-dark`) tokens; `--sf-color-*` are derived/resolved outputs.

## Issue Context
The doc later shows `-source-light` overrides, so the main fix is to clarify terminology and/or adjust the table to prevent incorrect theming guidance.

## Fix Focus Areas
- user-manual/colors.md[3-25]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools