@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).

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 MemorySave post-process signal block), 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";

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.

Onyx Hex material

The Onyx Hex design language gives every rectangular surface a soft-rounded square with a single top-right hex notch, every status dot / loader / play control a pointy-top hexagon, and every clickable a raised keycap with a 3px solid bottom edge. The shared material ships once, in the library, so no surface re-derives a clip-path. If you inherit @aisquare/ui/tailwind.preset you get it for free; otherwise import "@aisquare/ui/onyx-hex.css".

Typed class-name helpers (so you never hand-type the strings) come from the main barrel:

import { nx, hex, raise, elev, cn } from "@aisquare/ui";

<button className={cn(nx.b, raise)}>Publish</button>          {/* notched button keycap */}
<span className={cn("h-2 w-2 bg-success", hex)} />            {/* hexagonal status dot */}
<section className={cn(nx.l, elev.panel, "nx-keyline")} />    {/* notched panel + elevation + outline */}

Size to role

| Class | Helper | Role | |---|---|---| | .nx-l | nx.l | panels — rail, Brain region, ConfigPanel shell, large surfaces | | .nx-s | nx.s | cards — artifact tile, focus cards, hero, related, studio cards | | .nx-m | nx.m | tiles / fields — icon tiles, inputs, search, segmented track | | .nx-b | nx.b | buttons — primary/secondary, breadcrumb back/list, upload, nav back | | .nx-t | nx.t | chips — type chips, status pills, NEW/Draft chips, badges, the AikoMark container |

.hex (helper hex) replaces every circular dot/loader/play node. .raise (helper raise; .key / key is an alias) is the keycap: it lifts on :hover and presses flat on :active; set --edge: var(--ac2) on accent (Create/Publish) buttons.

Two rules a clipped surface forces (do not skip these)

1. Elevation must be filter: drop-shadow, never an outer box-shadow. clip-path clips an outer box-shadow away entirely. Use the elev.panel / elev.card / elev.soft classes (or filter: var(--dropPanel|--dropCard|--dropSoft)).
2. Outlines / selection / focus must be an INSET box-shadow keyline. A real border is sliced at the notch diagonal. Use .nx-keyline (rest) / .nx-keyline-active (selected) / an inset :focus-visible ring — never an outer outline.

The geometry is theme-agnostic (identical in light and .dark); only the elevation/edge token VALUES (--dropPanel/--dropCard/--dropSoft/--edge) flip via the .dark class. Colour/surface/accent tokens (--ac, --cardBd, --acSoft) are owned by the theme engine and referenced by name.

Never wrap the AikoMark in .hex. The cube glyph is itself a pointy-top hex silhouette, so a .hex container double-hexes it. The mark sits in a notched .nx-b / .nx-t chip.

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.