TOUCH GRASS // DESIGN SYSTEM

Open-source brutalist design system for products that refuse to whisper. Zero rounded corners. Zero animation. Token-driven neutral hierarchy. Geist Mono everywhere it counts.

By Thiago Xikota · Portfolio · Case study · Timeouts.app

---

The vibe (non-negotiable)

Most design systems are polite. Touch Grass is precise.

1. No rounded corners. border-radius: 0 is law.
2. No gray text. If it's not a token, it's not UI.
3. No motion. State changes snap; they don't dance.
4. Mono where it matters. Geist Mono for controls, stats, timers, command tone.
5. 48px minimum tap target. Always thumb-safe.
6. Tokens only. No rogue hex values inside components.

This system was built as the visual engine for Timeouts: a social gym for less screen time.

What's inside this machine

Package	Purpose
@touch-grass-ds/tokens	Style Dictionary source of truth. Ships CSS vars, Tailwind v4 @theme, W3C figma-tokens.json, and Swift constants (SPM).
@touch-grass-ds/react	React 19 library with primitives + patterns built on brutalist rules.
packages/docs-site	Vite + React docs site at localhost:5173, published at timeouts.app/touch-grass.

Visual proof

60-second quickstart

# install
pnpm add @touch-grass-ds/tokens @touch-grass-ds/react

/* app/globals.css */
@import "@touch-grass-ds/tokens"; /* or "@touch-grass-ds/tokens/tailwind" */
@import "@touch-grass-ds/react/styles/base.css";

import { Button } from "@touch-grass-ds/react";

export function Home() {
  return <Button variant="primary">START</Button>;
}

iOS / Swift

Add this repository in Xcode via Swift Package Manager:

https://github.com/thiagoxikota/touch-grass

Use tokens in Swift:

import TouchGrassTokens

let accent = TouchGrassTokens.colorEarned

Use the native iOS UI layer (SwiftUI primitives + social patterns):

import TouchGrassUI

let screen = TGCompetitionLoopScreen(
  state: .content(
    TGCompetitionLoopData(
      entries: [
        TGLeaderboardEntry(id: "you", rank: 1, displayName: "You", focusMinutes: 420, deltaMinutes: -35, streakDays: 9, isCurrentUser: true)
      ],
      streakDays: 9,
      sessionsCompleted: 22,
      screenTimeSavedMinutes: 420,
      challengeTitle: "Beat your record",
      challengeFriend: "Alex",
      challengePeriod: "This week"
    )
  )
)

TouchGrassUI ships state-ready screens (loading, offline, empty, content), DEBUG SwiftUI previews for all key states, rendered leaderboard snapshot-hash tests, and accessibility labels tuned for VoiceOver.

For golden snapshot updates in iOS tests, run UPDATE_TG_GOLDENS=1 swift test on a working Swift/Xcode toolchain, copy the printed hashes into packages/ios/Tests/TouchGrassUITests/Fixtures/leaderboard-snapshot-hashes.json, then re-run swift test.

Documentation

Full docs: timeouts.app/touch-grass

Design system contract: docs/contract.md — the normative specification covering color rules, motion bans, state model, accessibility, typography, asChild semantics, and enforcement. Uses MUST/SHOULD/MAY language per RFC 2119.

Cross-platform parity tracker: docs/ios-parity.md — current iOS vs web component coverage and accepted gaps.

Release checklist: docs/release-checklist.md — validation, snapshot fixture updates, parity updates, and release hygiene.

Local dev

corepack enable
corepack pnpm install
corepack pnpm tokens   # build token outputs first
corepack pnpm dev      # docs site on http://localhost:5173

Workspace commands:

corepack pnpm -r test
corepack pnpm -r build
corepack pnpm validate:all

Repo layout

touch-grass/
├── packages/
│   ├── tokens/       @touch-grass-ds/tokens
│   ├── ds/           @touch-grass-ds/react
│   ├── ios/          TouchGrassUI (SwiftUI components + tests)
│   └── docs-site/    docs app
├── brand/            brand assets
├── docs/             specs + superpowers
├── .github/          CI + issue templates + README assets
├── Package.swift     SPM entry point
└── package.json      workspace root

Roadmap

• v1.0.0 stable release (tokens + react package + docs + figma + npm)
• v1.1.0 select/combobox + chart primitives + expanded foundations docs

Where to use / where to get it

• npm: @touch-grass-ds/react · @touch-grass-ds/tokens
• Figma Community: Touch Grass DS
• Swift Package: thiagoxikota/touch-grass

Contributing

Read CONTRIBUTING.md first, especially the brutalist rules and component lockstep workflow.

License

MIT © Thiago Xikota