docs: differentiate identical/vague API descriptions

[jackgranatowski]

The 14 .sf-width-* utility classes all inherited the same section-banner
description in the generated API index (the only exact-duplicate group in
the whole surface). Give each its own precise annotation: the -10…-90
fractions each state their percentage cap, and the keyword variants
(full/auto/fit/min/max) describe their specific CSS width behaviour.

Also unify the 30 ramp lightness aliases (superlight/xlight/lighter/
darker/xdark/superdark across primary/secondary/tertiary/action/neutral)
so every one names its numeric equivalent (e.g. -darker → -600), matching
the format the -lighter/-superdark entries already used. Mapping verified
against core/tokens.css; base has no such aliases.

Edits are in the hand-authored docs/token-annotations.json; all generated
artifacts (api-index.{json,md}, llms.txt, configurator data, vscode custom
data) regenerated via npm run docs. check:annotations, check:doc-refs,
check:llm-guide, check:registry, audit:check, check:dead-knobs all pass.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_017dNWVwVRAS8Sn1qqKzTRqZ

Summary by CodeRabbit

• Documentation
  • Clarified color token aliases and their referenced CSS custom properties.
  • Improved descriptions of color shades and tints.
  • Documented percentage-based width utilities, including their caps and shrink-to-fit behavior.
  • Added descriptions for intrinsic sizing options such as full, auto, fit, minimum, and maximum width.

[coderabbitai]

📝 Walkthrough

Walkthrough

The documentation now identifies color alias source tokens and provides specific descriptions for percentage-based and intrinsic content-width utilities across API indexes, token annotations, and llms.txt.

Changes

Documentation metadata

Layer / File(s)	Summary
Color alias descriptions docs/api-index.json, docs/api-index.md, docs/token-annotations.json	Color descriptions now identify the source tokens for action, base, neutral, primary, secondary, and tertiary aliases.
Width utility descriptions docs/api-index.json, docs/api-index.md, docs/token-annotations.json, llms.txt	Width utility descriptions now specify percentage caps, centered shrinking, full and automatic width, and intrinsic sizing behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• codeslash-dev/SLASHED#351: Introduced the token annotation system updated by this PR.
• codeslash-dev/SLASHED#579: Added related color tint alias documentation.
• codeslash-dev/SLASHED#650: Introduced the width utilities documented by this PR.

Suggested reviewers: claude, kiro-agent

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: differentiating identical or vague API documentation descriptions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/framework-tokens-classes-ulkk75

---

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.}

[greptile-apps]

Greptile Summary

The PR replaces duplicate or vague API descriptions with precise documentation for width utilities and color-token aliases.

• Documents each .sf-width-* utility’s percentage cap or intrinsic sizing behavior.
• Names the numeric or alpha-token equivalent for color ramp aliases.
• Regenerates the API index, configurator data, CSS custom data, and LLM documentation from the hand-authored annotations.

Confidence Score: 5/5

The PR appears safe to merge, with the revised documentation matching the underlying CSS behavior and generated outputs.

No actionable defect remains: the width descriptions match their utility declarations, the color alias notes match their source token targets, and the generated artifacts consistently reproduce the source annotations.

Important Files Changed

Filename	Overview
docs/token-annotations.json	Updates the source annotations with width behavior and color alias descriptions that agree with the underlying CSS declarations.
docs/api-index.json	Regenerated API data consistently reflects the revised source annotations.
docs/api-index.md	Regenerated reference tables expose the new descriptions without identified inconsistencies.
configurator/src/data/api-index.generated.json	Regenerated configurator token metadata consistently carries the revised notes.
configurator/src/data/classes.generated.json	Regenerated class metadata carries the differentiated width utility descriptions.
dist/css-custom-data.json	Regenerated editor metadata consistently incorporates the updated token and utility documentation.
llms.txt	Regenerated LLM-facing documentation reflects the same API description updates.

_{Reviews (1): Last reviewed commit: "docs: name the -a5 alias in the -tint to..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@llms.txt`:
- Around line 553-554: Update the `.sf-width-auto` and `.sf-width-fit`
descriptions to accurately reflect block-flow sizing: state that
`inline-size:auto` fills available inline space subject to constraints, and that
`fit-content` uses content-based sizing capped by available space while wrapping
at permitted soft breaks.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 269dc479-78ab-4ab6-8461-1bc34ca283d1

📥 Commits

Reviewing files that changed from the base of the PR and between a9a80a3 and eba3a15.

⛔ Files ignored due to path filters (3)

• configurator/src/data/api-index.generated.json is excluded by !**/*.generated.*
• configurator/src/data/classes.generated.json is excluded by !**/*.generated.*
• dist/css-custom-data.json is excluded by !**/dist/**

📒 Files selected for processing (4)

• docs/api-index.json
• docs/api-index.md
• docs/token-annotations.json
• llms.txt

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
printf '%s\n' '--- llms.txt ---'
sed -n '544,557p' llms.txt
printf '%s\n' '--- utility declarations ---'
sed -n '220,255p' optional/utilities.css
printf '%s\n' '--- related width documentation/usages ---'
rg -n --glob '!node_modules' --glob '!dist' 'sf-width-(auto|fit)|inline-size:\s*(auto|fit-content)|fit-content' .

Repository: codeslash-dev/SLASHED

Length of output: 32745

---

🌐 Web query:

CSS inline-size auto normal block flow fit-content keyword sizing available space soft wrapping MDN CSS Sizing

💡 Result:

The inline-size CSS property is a logical sizing property that defines an element's size along its inline axis [1][2]. Because it is logical, its effect is relative to the element's writing-mode rather than physical orientation: in horizontal writing modes, it corresponds to width, while in vertical writing modes, it corresponds to height [1][3]. Key characteristics include: Axis Mapping: It works in tandem with block-size (which defines the dimension perpendicular to the inline axis) [1]. Using these logical properties allows layouts to adapt automatically when the writing mode or direction of content changes, enhancing internationalization and responsive design [2][3]. Sizing Keywords: inline-size accepts the same values as the traditional width and height properties [1][4]. Relevant intrinsic sizing keywords include: - auto: The initial value, typically causing the element to size automatically based on its content and layout context [4][5]. - min-content: Constrains the element to the smallest size required by its content (e.g., the length of the longest word or element) [6][5]. - max-content: Constrains the element to the largest size required by its content (e.g., the width of the content without line breaks) [6][5]. - fit-content: Adapts the element's size to its content while respecting the limits of its container, calculated as min(max-content, max(min-content, stretch)) [6][5]. Soft Wrapping and Available Space: The property interacts with the standard CSS box model and layout algorithms (like Flexbox or Grid) to determine how an element occupies available space [2][7]. When an element is sized with auto or fit-content, it naturally participates in soft wrapping; the browser will break text or inline content across lines to fit within the inline-size constraint, provided that the white-space property allows wrapping [2][6]. Advanced Manipulation: The calc-size function can be used to perform calculations on these intrinsic sizing keywords (like fit-content or max-content), which is not possible with the standard calc function [7]. This is particularly useful for creating fluid, animated, or responsive layouts where specific sizing constraints are required [7].

Citations:

• 1: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/inline-size
• 2: https://cssportal.com/css-properties/inline-size.php
• 3: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Logical_properties_and_values
• 4: https://www.w3schools.com/CSSref/css_pr_inline-size.php/css_ref_pseudo_classes.php
• 5: https://www.w3.org/TR/css-sizing/
• 6: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/fit-content
• 7: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/calc-size

---

🏁 Script executed:

#!/bin/bash
python3 - <<'PY'
from pathlib import Path
import re

css = Path("optional/utilities.css").read_text()
expected = {
    "sf-width-auto": "auto",
    "sf-width-fit": "fit-content",
}
for class_name, value in expected.items():
    pattern = rf"\.{re.escape(class_name)}\s*\{{\s*inline-size:\s*([^;]+);"
    match = re.search(pattern, css)
    assert match, f"missing declaration for {class_name}"
    actual = match.group(1).strip()
    assert actual == value, (class_name, actual, value)
    print(f"{class_name}: inline-size:{actual}")

print("normal-flow auto: automatic inline sizing; block-level width fills available space")
print("fit-content: min(max-content, max(min-content, available space)); soft breaks remain available")
PY

Repository: codeslash-dev/SLASHED

Length of output: 407

---

Update the descriptions for .sf-width-auto and .sf-width-fit.

In normal block flow, inline-size:auto fills the available inline space, subject to constraints. fit-content uses content-based sizing, capped by available space, and wraps at permitted soft breaks.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@llms.txt` around lines 553 - 554, Update the `.sf-width-auto` and
`.sf-width-fit` descriptions to accurately reflect block-flow sizing: state that
`inline-size:auto` fills available inline space subject to constraints, and that
`fit-content` uses content-based sizing capped by available space while wrapping
at permitted soft breaks.