@aisquare/ui

AISquare's design system: one package, three layers. Stock shadcn primitives, brand-flavored primitives, and composed AISquare components, all re-themed against the brand tokens. Replaces @aisquare/pretty as of v1.0.0 (pretty is retired; everything it owned now lives here).

Building with an AI coding agent? Read AGENTS.md first — it ships with the package (node_modules/@aisquare/ui/AGENTS.md) and points at registry/components.json, a machine-readable index of every component (layer, files, description) so an agent can discover what exists before writing anything custom.

What's in it

Three layers, closest-to-upstream first (mirrors the src/ layout and the playground nav):

• Stock shadcn (src/ui/) - byte-for-byte shadcn/ui v4 (new-york-v4) primitives, re-themed by tokens: Dialog, Sheet, AlertDialog, Select, RadioGroup, Slider, Table, Popover, Tabs, and more. Always reachable via the @aisquare/ui/stock subpath.
• Brand primitives (src/primitives/) - brand-flavored wrappers with the same API surface plus AISquare styling, motion, and defaults: Button, Input, PasswordInput, Checkbox, Switch, Label, Card, Avatar, AvatarGroup, Badge, Tooltip, Skeleton, Spinner, and more.
• Composed components (src/components/, incl. src/components/blocks/) - higher-level AISquare-original patterns: the Aiko* surface system, ChatInput, ChatLog, MessageRow, Markdown, EmptyState, ErrorState, SmartSearch, Stepper, GenerationTimeline, the Brain lifecycle-status vocabulary (StatusChip / StatusStripe / StatusProgress + statusToken / STATUS_ALIAS), the Brain ArtifactTile (one card for every artifact kind) + ArtifactFocus (its drill-in detail view), the chat-block renderers (BlockRenderer + interactive blocks + the post-process signal blocks MemorySave / EnrichedSuggestion / ToolGateCorrection / BetterAnswer), the ambient MoodLighting field (distinct from the BorderGlow / EditingBeam / BorderBeam border effects - see DESIGN.md "Field vs halo vs beam"), and the v1.4 component-port wave (see Adopting components below).

Plus SSR-safe hooks (src/hooks/: useDebouncedValue, useMediaQuery, useVoiceInput, useScrollToBottom, useReducedMotion, ...) and utilities (src/lib/: cn, the motion presets springs/easings/durations/transitions).

If you ever want the unstyled stock shadcn version of a primitive that has a brand wrapper, import it from the stock subpath:

import { Button } from "@aisquare/ui";              // brand-flavored
import { Button as StockButton } from "@aisquare/ui/stock"; // plain shadcn

Install

pnpm add @aisquare/ui

Wire it up

1. Tailwind preset - @aisquare/ui ships its own. Add it to your config so the brand tokens and animation utilities resolve:

   // tailwind.config.ts
   import aisquareUiPreset from "@aisquare/ui/tailwind.preset";
   export default {
     presets: [aisquareUiPreset],
     content: [
       "./src/**/*.{ts,tsx}",
       "./node_modules/@aisquare/ui/dist/**/*.{js,mjs}", // scan the lib's class strings
     ],
   };

2. CSS tokens - the preset maps the tokens; if you use Sidebar or Chart, also import the extras CSS:

   /* app/global.css */
   @import "@aisquare/ui/tokens/shadcn-extras.css"; /* optional: Sidebar / Chart vars */

3. Import and use:

   import { Dialog, DialogContent, DialogTrigger, Button } from "@aisquare/ui";

No React / no Tailwind? Use the standalone tokens CSS

Building outside this stack (a plain HTML prototype, another framework, or handing the brand tokens to an AI agent that isn't wiring up the full package)? docs/aisquare-foundations.css is a framework-free, dependency-free stylesheet with the same color/typography/spacing/radius/elevation/motion foundations as the Tailwind preset — just <link> it, no build step. It documents its own usage inline (two-tier color model, dark mode, overriding).

Adopting components (for consumer apps)

Wiring these components into a consumer app (the unified Creator Studio app, or any other)? Read docs/ADOPTION.md. It has a per-component reference for the v1.4 component-port wave: the real import, the props that matter, what hand-built code each one replaces and where, a paste-ready snippet, and the gotchas.

Two one-time setup steps a consumer must do or the components render unstyled (covered in detail in the doc):

1. Add the @aisquare/ui/tailwind.preset to your Tailwind config (step 1 above).
2. Define the --success and --warning CSS vars in your :root (the other shadcn-alias tokens usually already exist). Several components use them for status and success/error states.

The initiative is tracked in aisquare-ui#37; the adopt-side checklist is aisquare-studio-unified#24.

Glass material

The current shape system is plain rounded surfaces — buttons are a pill (rounded-full), cards/panels/fields use the standard rounded-md/lg/xl/2xl scale with a real CSS border and box-shadow — see DESIGN.md. The Onyx Hex notch/keycap/hexagon material this section used to document is fully retired now that every consumer has migrated; the one piece still live is the glass material — frosted elevation for FLOATING surfaces (GlassSurface, the AppShell Brain region).

A glass panel is two stacked layers, because backdrop-filter and filter cancel on the same DOM node. If you inherit @aisquare/ui/tailwind.preset you get it for free; otherwise import "@aisquare/ui/onyx-hex.css" (the filename is legacy).

import { glass, cn } from "@aisquare/ui";

<div className={cn(glass.back, "absolute inset-0")} />       {/* backing layer — filter: drop-shadow only */}
<div className={cn(glass.panel, "relative rounded-2xl")}>    {/* glass layer — backdrop-filter only */}
  ...
</div>

glass.panel is the floating-panel rim (--glassBd); glass.composer is the accent-lined composer bar (--acLine). See GlassSurface's source for the full two-layer composition (backing + frost + a real border for the rim keyline).

Agents

This library is the single source of truth for UI, and that is enforced rather than documented: the repo ships an MCP server plus a Claude Code skill that make agents search the library first, extend a component upstream when it almost fits, and add the component here when it is genuinely missing.

# across every repo
claude plugin marketplace add AISquare-Studio/aisquare-ui
claude plugin install aisquare-ui@aisquare

# or into one consumer app (the server and index ship inside the package)
npx aisquare-ui-agent init

Eleven tools: intent search, props and cva variants, design tokens, the 46 governance rules, a usage linter, a conforming component scaffolder, and a doctor for the "everything renders unstyled" class of setup bug. See mcp/README.md and skills/aisquare-ui/.

If you add a component, run pnpm agent:index so agents can find it (pnpm build does this for you).

Explore the components

• Playground (deployed): ui.aisquare.studio - every component grouped by layer, with live demos and per-example code.
• Storybook (local): pnpm storybook.

Versioning

Semver. Visual changes that are not strictly opt-in bump minor. Breaking API changes (renamed exports, removed variants) bump major. See CONTRIBUTING.md.

How updates from upstream shadcn land here

Stock primitives in src/ui/ are byte-for-byte mirrors of ui/apps/v4/registry/new-york-v4/ui/<name>.tsx, with only import-path rewrites. To pull an upstream update:

pnpm import:shadcn          # re-imports the v0.1.0 set
pnpm import:shadcn --all    # re-imports everything in scope
pnpm typecheck && pnpm build

Review the diff, bump the version, ship a release.

License

MIT. Derived from shadcn-ui/ui (MIT) - see LICENSE.