Replace "no grey text" rule with 3-tier neutral hierarchy tokens and opacity ban

[Copilot]

The DS lacked readable text hierarchy — everything was #FFFFFF or nothing. This replaces the old "no grey text" rule with a strict, token-driven neutral tier while banning opacity/rgba-based hierarchy.

Tokens

• Replaced color.muted → color.fgMuted (#B3B3B3, >7:1), added color.fgSubtle (#808080, >4.5:1, metadata-only), color.hairlineStrong (#333333)
• Light mode equivalents added; all outputs regenerated (CSS, Tailwind, Figma JSON, Swift, JS)

Components

• Field description → fg-muted, Input placeholder → fg-subtle
• LeaderboardRow handle → fg-muted, removed rgba(166,255,0,0.06) → bg-alt
• Stat meta labels → fg-muted, SessionSummaryCard date → fg-muted

Enforcement

• lint-brutal.mjs + eslint-plugin-touch-grass: new rules ban opacity- utilities and rgba(..., 0.x) in DS source

// New lint violations (scoped to packages/ds/src/)
{ regex: /(?<![a-zA-Z-])opacity-(?!0\b)\d+/g, message: 'No opacity-based hierarchy...' },
{ regex: /rgba\([^)]+,\s*0\.\d+\)/g, message: 'No alpha rgba() in DS styles...' }

Docs & contract

• BRAND.md, README.md, CONTRIBUTING.md: "zero grey text" → "no opacity hierarchy"
• Color page: 3 new swatches, rule renamed NO GREY TEXT → NO OPACITY HIERARCHY
• Typography page: new "THREE TIERS OF TEXT COLOR" section teaching fg / fg-muted / fg-subtle usage
• Accessibility, Releases, Spacing pages: migrated --color-muted refs

Core constraints preserved

Radius 0, zero motion, tokens-first, 48px tap targets, mono usage — all unchanged.

Original prompt

Update the existing WIP PR on thiagoxikota/touch-grass (currently titled "[WIP] Fix inconsistencies in documentation, tokens, and components", branch copilot/fix-inconsistencies-in-design-system) to incorporate the revised direction:

Updated direction (authoritative)

Touch Grass should be bold/creative/viral/pleasing, while preserving core authenticity:

• Radius stays 0.
• No motion stays (no transitions/animations).
• Tokens-first stays.
• 48px min tap target stays.
• Mono usage stays as described.

Key change: allow greys/neutrals for hierarchy

Replace the old "No grey text" rule with:

• Allow neutrals/greys, but only via tokens.
• Ban opacity-based hierarchy in DS-owned CSS: no using opacity or alpha rgba() to mute text; instead use neutral tokens.

Required implementation changes

1. Tokens: introduce a small, strict neutral tier (Option A):

   • Add text hierarchy tokens: --color-fg, --color-fg-muted, --color-fg-subtle.
   • Ensure fg-subtle is used for metadata/labels only, not body copy.
   • Add border hierarchy tokens if needed: --color-hairline, --color-hairline-strong.
   • Keep existing accent semantics (earned, danger) and backgrounds (bg, bg-alt).
   • Regenerate outputs: dist/tokens.css, dist/tailwind.theme.css, dist/figma-tokens.json, Swift outputs, etc.

2. Docs and contract:

   • Update docs/contract.md (or equivalent) and README to reflect the new neutrality rule.
   • Update Foundations/Color + Foundations/Typography pages to explicitly teach the 3-tier text hierarchy and the "no opacity hierarchy" ban.

3. Components:

   • Update primitives/patterns to use fg-muted / fg-subtle where appropriate: labels, helper text, placeholders, metadata.
   • Keep body copy on fg/fg-muted.

4. Enforcement:

   • Strengthen lint checks to fail on opacity: and alpha rgba() usage (scoped to DS packages; exclude generated token outputs).
   • Keep existing motion bans (transition/animation).

5. Ensure CI/tests/build pass.

Notes

• Keep changes minimal and mechanical, but consistent.
• Do not introduce new runtime deps unless necessary.
• Update the WIP PR rather than opening a new PR.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: the repo is the source of truth, both

Assistant: To “fix all” (docs + code) I need you to explicitly tell me whether you want a PR opened, because code changes should land as a pull request.

Choose one

1. Open a PR in thiagoxikota/touch-grass (tell me the base branch: main?)
2. No PR — just give you a detailed plan + exact patches you can apply

What I will fix (both docs + code), rigidly

• Make the repo the single spec by adding a normative contract (states, a11y, typography hierarchy, “no grey” interpretation, motion rule, exceptions like asChild).
• Align tokens/components to that contract:
  • enforce state deltas consistently (hover/focus/active/disabled/loading)
  • remove/forbid any “soft” patterns (opacity greys, transitions) if present
  • tighten semantics around asChild + disabled behavior
• Update docs-site pages to match the spec and add a compliance checklist.

Reply with:

• PR or no PR
• base branch name (e.g. main)
• any “hard rules” you want added (or confirm the existing list is final).

User: pr

Assistant: I’m waiting for the PR creation run to finish; once it completes, I’ll summarize exactly what changed (docs, tokens, components, and enforcement) and what you should review before merging.

User: @copilot Accepted Confirmation: Confirm agent session

Assistant: Copilot coding agent has started working on the PR. You can track progress at the task link below.

data:
  - title: 'Unify Touch Grass contract and enforce it across docs, tokens, and components'
    repository: thiagoxikota/touch-grass
    url: https://github.com/copilot/tasks/pull/PR_kwDOSCDcXM7Sf_K1?session_id=d696ec16-bfbd-4cf6-afa6-c8d194543d85
    state: queued

User: any other suggestions?

Assistant: Yes—assuming you keep the “brutalist, no motion, no grey” stance, these are the highest-leverage additions I’d suggest beyond the PR scope.

1) Make “No grey text” operational (not vibes)

Define a text hierarchy system that doesn’t rely on grey/opacity:

• Primary: --color-fg
• Secondary: same color, different treatment (weight, size, tracking, casing, underline, border rule, layout grouping)
• Tertiary/metadata: same color, but constrained by spacing + typographic scale (not alpha)
  This prevents every screen from becoming “everything screams equally.”

2) Add a “Decision log” for weird rules

A docs/decisions/ folder with short ADR-style notes:

• Why no transitions (and the tradeoffs you accept)
• Why no neutrals
• Why 48px always
• Why mono for certain roles
  This stops future contributors from “fixing” the system back into a generic one.

3) Expand tokens...

This pull request was created from Copilot chat.

[thiagoxikota]

@copilot resolve the merge conflicts in this pull request

[thiagoxikota]

@copilot resolve the merge conflicts in this pull request

[thiagoxikota]

ok