How to Use

Optimistic is named for the optimistic update, the pattern where an interface shows the result of an action the instant you take it, then quietly reconciles with the server. The design system is built in that same spirit: fast, confident, and honest when reality disagrees. Read the philosophy for the long version, or start below. Everything lives in one repository: github.com/subinsab/Optimistic.

The stack is Next.js and React, so anything that runs a modern Node app runs this. Confirm two things first: node -v and git --version.

Four free tools. Install Node and Git to run the project; VS Code and Claude are how you will work in it.

Four steps to get the documentation site and the full component source running on your machine.

git clone https://github.com/subinsab/Optimistic.git

cd Optimistic
npm install

npm run dev
# ready on http://localhost:3000

npm run build
npm start

The kit is shadcn-style: instead of a locked npm package, an installer copies the tokens and the components you pick straight into your project, so you own and can reshape every file.

cd Optimistic/optimistic-ui

node install.mjs button notification --dir src/ui

/* global.css */
@import "./ui/tokens.css";

import { Button } from "./ui/components/button/button";

<Button variant="warm">Ship it</Button>

Once the tokens are imported, every foundation is a set of CSS variables you consume with var(--token). Nothing is hard-coded, so a change at the token layer flows to every component at once. Here is how to use each one.

.card {
  background: var(--bg-panel);
  color: var(--text-primary);
  border: 1px solid var(--border-default);
}
.card__cta { background: var(--color-brand-500); }

.title { font: var(--type-header-1); letter-spacing: var(--type-header-1-tracking); }
.copy  { font: var(--type-body-1);   letter-spacing: var(--type-body-1-tracking); }

.panel { padding: var(--space-300); }        /* 24px */
.row   { display: flex; gap: var(--space-100); } /* 8px  */

<div class="o-container">
  <div class="o-row">
    <div class="o-col" style="--m:4; --t:8; --d:8">Main</div>
    <div class="o-col" style="--m:4; --t:8; --d:4">Aside</div>
  </div>
</div>

.button { border-radius: var(--radius-md); }   /* 6px  */
.card   { border-radius: var(--radius-xl); }   /* 12px */
.chip   { border-radius: var(--radius-full); }

.divider { border-top: 1px solid var(--border-default); }
.popover { box-shadow: 0 8px 24px rgba(0, 0, 0, .42); }

/* mobile-first: 768px tablet, 1024px web */
.grid { grid-template-columns: 1fr; }
@media (min-width: 768px)  { .grid { grid-template-columns: repeat(2, 1fr); } }
@media (min-width: 1024px) { .grid { grid-template-columns: repeat(4, 1fr); } }

The system is atomic. A decision becomes a token, tokens form components, components form products, one unbroken line from Figma to shipped software.