| name | g4rcez-components |
| description | Use when: setting up @g4rcez/components in a new project, migrating native HTML elements or hand-rolled UI to this design system, building any React UI that should use @g4rcez/components, or when the user's project already has @g4rcez/components as a dependency. Covers installation, Tailwind v3 preset, Tailwind v4 CSS-first setup, theming with createTokenStyles/TokenRemap, ComponentsProvider/tweaks, parsers, the full component catalog (components, hooks, React, UI, design-system, tokens, Tailwind, forms, modals, notifications, tables, calendar, theming), and native-element migration.
|
Loaded automatically when this package is present. Read fully before writing or modifying UI.
@g4rcez/components — Agent Skill
A React design system built on Tailwind CSS and design tokens. This skill covers
installation, Tailwind setup (v3 and v4), theming APIs, conventions, the full
component catalog, and migration from native HTML patterns.
1 — Installation
pnpm add @g4rcez/components
The package ships:
dist/ — compiled JS/TS and CSSdist/index.css — main stylesheetai/SKILL.md — this fileai/docs/ — per-component documentation (51 pages)
Access any file via the package specifier: @g4rcez/components/ai/SKILL.md, @g4rcez/components/ai/docs/Button.md, etc.
2 — Tailwind Setup
v3 (preset-based)
Add the library preset to tailwind.config.ts. The preset registers all design tokens as Tailwind utilities.
import preset from "@g4rcez/components/preset.tailwind";
export default {
presets: [preset],
content: ["./src/**/*.{ts,tsx}", "./node_modules/@g4rcez/components/dist/**/*.js"],
};
v4 (CSS-first)
Import Tailwind and the library stylesheet, then reference the library config via @config:
@import "tailwindcss";
@import "@g4rcez/components/dist/index.css";
@config "./tailwind.config.ts";
The library's tailwind.config.ts uses plugin.tailwind (the v4-compatible plugin):
import plugin from "@g4rcez/components/plugin.tailwind";
export default {
plugins: [plugin],
content: ["./src/**/*.{ts,tsx}", "./node_modules/@g4rcez/components/dist/**/*.js"],
};
Theme class (required for both versions)
Apply light or dark on your root element:
<html className="light">...</html>
<html className="dark">...</html>
ComponentsProvider (optional, required for dark-mode toggle)
Wrap your app root to enable i18n strings, locale-aware masks, and Modal.confirm:
import { ComponentsProvider } from "@g4rcez/components";
export default function App({ children }) {
return <ComponentsProvider locale="en-US">{children}</ComponentsProvider>;
}
3 — Theme Setup with createTokenStyles
Use createTokenStyles to generate scoped CSS strings for light and dark themes, then inject them into <head> via a <style> element.
import { createTokenStyles, createCssProperties, type TokenRemap } from "@g4rcez/components";
createTokenStyles(theme, map?) — returns a scoped CSS string, e.g. html { --primary: … }createCssProperties(theme, map?) — returns an inline style object with CSS custom properties- When
map.name is set (e.g. "dark"), the output scopes to html.dark { … }
- Use
createTokenStyles for <style> injection; use createCssProperties for inline style props
Two-theme pattern (light + dark)
import { createTokenStyles, type TokenRemap, defaultLightTheme, defaultDarkTheme } from "@g4rcez/components";
const tokenRemap: TokenRemap = {
colors: (t) => {
t.value = t.value.replace("hsla(", "").replace(/\)$/, "");
return t;
},
};
const stylesLight = createTokenStyles(defaultLightTheme, tokenRemap);
const stylesDark = createTokenStyles(defaultDarkTheme, { ...tokenRemap, name: "dark" });
4 — TokenRemap
TokenRemap transforms each design token value before it is emitted as a CSS custom property.
export type TokenRemap = Partial<
Record<"colors" | "spacing" | "rounded" | "customTokens" | "zIndex", (t: Token) => Token> & { name: string }
>;
Stripping hsla(…) in the colors transformer is required for Tailwind opacity utilities (bg-primary/50) — they expect raw channel values (210 40% 60%), not a wrapped hsla(210 40% 60%).
5 — ComponentsProvider & Tweaks
import { ComponentsProvider, type Tweaks, parsers } from "@g4rcez/components";
const tweaks: Tweaks = {
table: {
sorters: true,
filters: true,
operations: true,
sticky: 55,
},
};
<ComponentsProvider locale="en-US" tweaks={tweaks} parser={parsers.hsla}>
{children}
</ComponentsProvider>;
6 — Key Conventions
Never use raw Tailwind color classes
<div className="bg-blue-500 text-white">...</div>
<div className="bg-primary text-primary-foreground">...</div>
Always use component theme / variant props
<button className="bg-red-600 text-white">Delete</button>
<Button theme="danger">Delete</Button>
7 — Component Catalog
The library supports both barrel imports and sub-path imports for tree-shaking:
Button — @g4rcez/components or @g4rcez/components/buttonInput — @g4rcez/components or @g4rcez/components/inputModal — @g4rcez/components or @g4rcez/components/modalTable — @g4rcez/components or @g4rcez/components/tableSelect — @g4rcez/components or @g4rcez/components/select
See @g4rcez/components/ai/docs/index.md for the complete export list.
8 — Migration from Native HTML
<button> → Button<input type="text"> → Input<input type="date"> → DatePicker<input type="checkbox"> → Checkbox<select> → Select- Custom modal / dialog →
Modal (type "dialog")
- Side panel / drawer →
Modal (type "drawer")
- Toast / notifications →
Notifications
- Data table →
Table
9 — Per-Component Documentation
Each component has a dedicated doc page with full props, design tokens, and usage examples:
@g4rcez/components/ai/docs/<ComponentName>.md
Examples:
@g4rcez/components/ai/docs/Button.md@g4rcez/components/ai/docs/Input.md@g4rcez/components/ai/docs/Modal.md@g4rcez/components/ai/docs/Table.md@g4rcez/components/ai/docs/Form.md
