@goliapkg/gds

v2.2.0

Published

9 hours ago

GOLIA Design System — enterprise-grade UI component library with contextual depth, glass materials, AI-native structure, and 10 design principles

0High
0Medium
0Low

goliapanda

react design-system component-library ui tailwindcss typescript ai-native glass-ui dark-mode enterprise

@goliapkg/gds

GOLIA Design System — production-grade React UI component library built by GOLIA.

380+ components across 8 architectural layers, from design tokens to full-page patterns.

Features

380+ components across 8 layers (tokens → primitives → atoms → molecules → organisms → charts → patterns)
Strict layer architecture — dependency constraints enforced by ESLint, anti-corruption wrappers for all external deps
93% branch coverage — 393 test files, 3400+ test cases, all layers above 90%
AI-native — semantic data-component/data-variant/data-state attributes, typed props, machine-readable docs
Contextual depth — components auto-scale spacing, radius, shadow, typography based on nesting depth
Glass material — frosted translucency as first-class material system via glass prop
Motion system — spring physics animation vocabulary via motion prop
Dark-native — designed for dark mode first, light mode derived
Keyboard-first — every interactive element has keyboard support, visible focus indicators, focus trapping in overlays
5-axis theming — density, elevation, glass, motion, shape — all controllable at runtime via Jotai atoms
Tree-shakeable — per-layer subpath exports, ESM-only, sideEffects: false

Install

bun add @goliapkg/gds

import { Button, Card, CardHeader, CardContent } from '@goliapkg/gds'
import '@goliapkg/gds/tokens.css'

function App() {
  return (
    <Card glass>
      <CardHeader title="Hello GDS" />
      <CardContent>
        <Button variant="primary" motion="scale">
          Get Started
        </Button>
      </CardContent>
    </Card>
  )
}

Integration Guide (Tailwind v4)

1. Install

bun add @goliapkg/gds

2. CSS setup (`index.css`)

@import 'tailwindcss';
@import '@goliapkg/gds/tokens.css';
@import '@goliapkg/gds/theme.css';

/* required: let Tailwind scan GDS component classes */
@source "../node_modules/@goliapkg/gds/dist/**/*.js";

tokens.css provides GDS utilities (gds-shadow-sm, gds-radius-card, etc.). theme.css maps GDS tokens to Tailwind's built-in utilities (shadow-sm, rounded-lg, bg-bg, text-fg, etc.) so you can use standard Tailwind classes with GDS theme values.

3. Theme provider (`app.tsx`)

import { Provider } from 'jotai'
import { useFonts, useThemeEffect } from '@goliapkg/gds/systems'

function ThemeInit() {
  useThemeEffect()
  useFonts() // auto-inject CJK fonts (Noto Sans SC/JP/KR) from Google Fonts CDN
  return null
}

function App() {
  return (
    <Provider>
      <ThemeInit />
      {/* your app */}
    </Provider>
  )
}

4. FOUC prevention (`index.html`)

Add this script to <head> to prevent flash of unstyled content on page load:

<script>
  try {
    const t = JSON.parse(localStorage.getItem('gds-theme') ?? '{}')
    if (t.mode === 'dark' || (!t.mode && matchMedia('(prefers-color-scheme:dark)').matches))
      document.documentElement.classList.add('dark')
  } catch {}
</script>

Troubleshooting

GDS classes not working? — Make sure you have the @source line in your CSS. Tailwind v4 won't scan node_modules by default.
bun add shows "no version matching"? — Delete bun.lock and re-run bun install. This is a bun registry cache issue.

Subpath Imports

Import only what you need for optimal bundle size:

// full library (re-exports everything)
import { Button, Dialog, DataTable } from '@goliapkg/gds'

// per-layer imports (tree-shaking friendly)
import { Button, Input } from '@goliapkg/gds/primitives'
import { Avatar, Switch } from '@goliapkg/gds/atoms'
import { Card, Dialog, Tabs } from '@goliapkg/gds/molecules'
import { DataTable, Calendar } from '@goliapkg/gds/organisms'
import { BarChart, LineChart } from '@goliapkg/gds/charts'
import { AdminLayout, Hero } from '@goliapkg/gds/patterns'
import { cx, focusCls, renderPortal } from '@goliapkg/gds/utils'

// theme & tokens
import { useThemeEffect, useSetThemeMode } from '@goliapkg/gds/systems'
import { generateDefaultCssVars } from '@goliapkg/gds/tokens'

Architecture

src/
├── l0-tokens/      design tokens: color math, sizing, radius, shadow, glass, motion, gestures
├── l1-systems/     theme engine (Jotai atoms), 5-axis dimensional state
├── l2-primitives/  31 stateless visual blocks (Button, Input, Badge, Spinner...)
├── l3-atoms/       71 simple composed elements (Avatar, Checkbox, Tooltip, Rating...)
├── l4-molecules/   109 multi-part components (Card, Dialog, Tabs, Select, ColorPicker...)
├── l5-organisms/   74 complex features (DataTable, GanttChart, Calendar, Kanban...)
├── l6-charts/      37 data visualizations (Bar, Line, Heatmap, Gantt, Flame, Realtime...)
├── l7-patterns/    55 page-level layouts (Dashboard, Admin, Hero, LoginForm...)
└── utils/          anti-corruption layer (cx, a11y, dom, types, motion, glass, portal)

Layer Dependency Rules

Each layer has strict import constraints enforced by ESLint:

| Layer | Can Import From | External Deps | |-------|----------------|---------------| | L0 tokens | — | tailwindcss | | L1 systems | L0 | react, jotai | | L2 primitives | L0, L1, utils | react, cva | | L3 atoms | L0–L2, utils | + lucide-react | | L4 molecules | L0–L3, utils | + lucide-react | | L5 organisms | L0–L4, utils | + lucide-react | | L6 charts | L0, utils | recharts | | L7 patterns | L0–L5, utils | react |

Anti-corruption wrappers: cx() for clsx+tailwind-merge, VariantProps for CVA types, renderPortal() for react-dom. Direct imports of these packages are blocked by ESLint.

Development

git clone [email protected]:goliajp/gds.git
cd gds
bun install
bun dev              # website at localhost:5175
bun test             # run vitest
bun run test:coverage # coverage report (93%+ branches)
bun run check        # test + typecheck + lint
bun run build        # build library

Quality

| Metric | Value | |--------|-------| | Test files | 399 | | Test cases | 3,457+ | | Branch coverage | 93%+ | | Line coverage | 97%+ | | TypeScript | strict, zero any | | a11y | focus trap, keyboard nav, ARIA roles | | SSR safe | all browser APIs guarded |

For AI Agents

GDS is designed to be learned and applied by AI. Key entry points:

| What you need | Where to look | |---------------|---------------| | All exports | src/index.ts | | Component pattern | any src/l3-atoms/*.tsx (canonical) | | Design tokens | src/l0-tokens/ | | Layer rules | src/l0-tokens/deps.ts | | Philosophy | .claude/rules/gds-philosophy.md | | Standards | .claude/rules/gds-lib.md | | Live demos | web/src/items/ (150+ demos) |

Every component: CVA variants → typed Props → forwardRef → cx() → focusCls → data-component. Learn one, apply to all.

Tech Stack

React 19 + TypeScript (strict)
Tailwind CSS 4 with semantic design tokens
CVA for variant management
Jotai for theme state
Recharts 3 for charts
Lucide for icons
Vite 8 for build
Vitest for testing

License

MIT — GOLIA

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@goliapkg/gds

Features

Install

Integration Guide (Tailwind v4)

1. Install

2. CSS setup (index.css)

3. Theme provider (app.tsx)

4. FOUC prevention (index.html)

Troubleshooting

Subpath Imports

Architecture

Layer Dependency Rules

Development

Quality

For AI Agents

Tech Stack

License

2. CSS setup (`index.css`)

3. Theme provider (`app.tsx`)

4. FOUC prevention (`index.html`)