@ancatag/at-design

A shared design system package providing 29 reusable UI components with theme-agnostic styling. Built with React, TypeScript, Tailwind CSS, and Radix UI primitives.

Installation

Install Package

npm install @ancatag/at-design
# or
pnpm add @ancatag/at-design
# or
yarn add @ancatag/at-design

This is a public npm package - no authentication required!

From Git Repository (Development)

{
  "dependencies": {
    "@ancatag/at-design": "github:ancatag/at-design#v{version}"
  }
}

Or for latest from main branch:

{
  "dependencies": {
    "@ancatag/at-design": "github:ancatag/at-design"
  }
}

From Local File Path (Development)

{
  "dependencies": {
    "@ancatag/at-design": "file:../path/to/at-design"
  }
}

Quick Start

1. Import Base Styles

In your app's main CSS file (e.g., globals.css or index.css), import the design system base styles:

/* Import design system base styles */
@import "@ancatag/at-design/styles/tokens";
@import "@ancatag/at-design/styles/animations";
@import "@ancatag/at-design/styles/base";

@import "tailwindcss";

/* Override with your app's theme */
@theme {
  --color-primary: #your-color;
  --color-background: #your-bg;
  /* ... other theme overrides */
}

2. Import Components

import { Button, Card, Input } from "@ancatag/at-design";

3. Use Components

<Card>
  <CardHeader>
    <CardTitle>Hello</CardTitle>
  </CardHeader>
  <CardContent>
    <Input placeholder="Enter text" />
    <Button>Submit</Button>
  </CardContent>
</Card>

Component Inventory

Form Components (9)

• Input - Text input field
• Textarea - Multi-line text input
• Select - Dropdown selection menu
• Combobox - Searchable dropdown with custom values
• Checkbox - Binary checkbox
• RadioGroup - Radio button group
• Switch - Toggle switch
• Slider - Range slider
• Label - Form label

Display Components (8)

• Card - Container card with header/content/footer
• GlassCard - Glass morphism card with gradients
• Badge - Status indicator or label
• Avatar - User/entity avatar with image and fallback
• IconBadge - Badge with icon, value, and label
• StatCard - Statistics card with icon and value
• Skeleton - Loading placeholder
• Progress - Progress bar indicator

Navigation & Layout (3)

• Tabs - Tabbed interface
• Table - Data table
• ResponsiveTable - Mobile-responsive table with card view

Overlay Components (6)

• Dialog - Modal dialog
• AlertDialog - Alert dialog for confirmations
• Sheet - Slide-out panel
• BottomSheet - Mobile-optimized bottom sheet
• Tooltip - Hover tooltip
• Toast - Toast notification system

Feedback Components (1)

• Alert - Alert message

Action Components (2)

• Button - Primary action button
• DropdownMenu - Dropdown menu

Error Pages (1)

• ErrorPage - Customizable error page component
• NotFoundPage - Pre-configured 404 page
• ServerErrorPage - Pre-configured 500 page
• ForbiddenPage - Pre-configured 403 page
• UnauthorizedPage - Pre-configured 401 page

Total: 29 components

Multi-App Usage

This design system powers multiple applications with consistent UI components:

• nova-route - AI platform dashboard
• openchat - AI character storytelling platform

Automated Releases

The design system uses GitHub Actions for automated versioning and publishing:

1. Push to main → Automatic version bump based on conventional commits
2. Build & publish → Package published to npm registry
3. Create release → Git tag and GitHub release created
4. Update consuming apps → Apps can update to latest version

Version Update Process

Consuming applications should regularly update to the latest version:

# Check latest version
pnpm info @ancatag/at-design

# Update to latest
pnpm update @ancatag/at-design

# Or pin to specific version
pnpm add @ancatag/at-design@^1.0.0  # Replace with desired version

See docs/DESIGN_SYSTEM_WORKFLOW.md for complete workflow documentation.

Theme Customization

The design system uses CSS custom properties (CSS variables) for theming. All components automatically use these tokens, which can be overridden in your app's CSS.

Available CSS Variables

/* Colors */
--color-background
--color-foreground
--color-card
--color-card-foreground
--color-popover
--color-popover-foreground
--color-primary
--color-primary-foreground
--color-secondary
--color-secondary-foreground
--color-muted
--color-muted-foreground
--color-accent
--color-accent-foreground
--color-destructive
--color-destructive-foreground
--color-border
--color-input
--color-ring

/* Border Radius */
--radius-lg
--radius-md
--radius-sm

/* Shadows */
--shadow-sm
--shadow-md
--shadow-lg
--shadow-xl

Example: Custom Theme

@theme {
  /* Light Mode - Custom Theme */
  --color-background: #f5f5f7;
  --color-foreground: #1d1d1f;
  --color-primary: #0071e3;
  --color-primary-foreground: #ffffff;
  /* ... */
}

:root.dark {
  /* Dark Mode - Custom Theme */
  --color-background: #000000;
  --color-foreground: #f5f5f7;
  --color-primary: #0a84ff;
  /* ... */
}

Usage Examples

Basic Form

import { Input, Label, Button, Card, CardContent, CardHeader, CardTitle } from "@ancatag/at-design";

function LoginForm() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Login</CardTitle>
      </CardHeader>
      <CardContent>
        <div className="space-y-4">
          <div>
            <Label htmlFor="email">Email</Label>
            <Input id="email" type="email" placeholder="[email protected]" />
          </div>
          <div>
            <Label htmlFor="password">Password</Label>
            <Input id="password" type="password" />
          </div>
          <Button>Sign In</Button>
        </div>
      </CardContent>
    </Card>
  );
}

404 Error Page

import { NotFoundPage } from "@ancatag/at-design";

function NotFound() {
  return (
    <NotFoundPage
      showHomeButton
      showBackButton
      onHomeClick={() => window.location.href = "/"}
    />
  );
}

Custom Error Page

import { ErrorPage } from "@ancatag/at-design";
import { AlertCircle } from "lucide-react";

function CustomError() {
  return (
    <ErrorPage
      code="404"
      title="Page Not Found"
      description="The page you're looking for doesn't exist."
      icon={AlertCircle}
      showHomeButton
      showBackButton
      variant="full"
    />
  );
}

Icon Badge

import { IconBadge } from "@ancatag/at-design";
import { Coins } from "lucide-react";

function TokenDisplay() {
  return (
    <IconBadge
      icon={Coins}
      value="1,234"
      label="Open Tokens"
      variant="yellow"
      size="lg"
    />
  );
}

Responsive Table

import { ResponsiveTable } from "@ancatag/at-design";

const columns = [
  {
    key: "name",
    header: "Name",
    render: (item) => item.name,
    mobileLabel: "Name",
  },
  {
    key: "email",
    header: "Email",
    render: (item) => item.email,
    mobileLabel: "Email",
  },
];

function UserTable({ users }) {
  return (
    <ResponsiveTable
      data={users}
      columns={columns}
      keyExtractor={(user) => user.id}
      onRowClick={(user) => console.log(user)}
    />
  );
}

Component Documentation

For detailed component documentation, see docs/COMPONENTS.md and docs/COMPONENT_CATEGORIES.md.

Dependencies

Peer Dependencies

• react ^19.2.3
• react-dom ^19.2.3

Direct Dependencies

• Radix UI primitives (for accessibility and behavior)
• lucide-react (for icons)
• sonner (for toast notifications)
• class-variance-authority (for variant management)
• clsx & tailwind-merge (for class name utilities)

Development

Building

pnpm build

This compiles TypeScript to the dist/ directory with declaration files and source maps.

Type Checking

pnpm type-check

Cleaning Build Output

pnpm clean

Publishing

Automatic CI/CD Release (Recommended)

Everything is handled automatically by GitHub Actions! Just push to main:

1. Make changes and commit using Conventional Commits:

   git commit -m "feat: add new component"
   git push origin main

2. CI automatically:

   • Detects version bump type from commits
   • Bumps version in package.json
   • Updates CHANGELOG.md
   • Builds the package
   • Publishes to npm registry as public package
   • Creates git tag and GitHub release

No manual steps required!

Version Bump Detection

CI analyzes commit messages since the last tag:

• feat: or feature: → Minor bump (0.1.0 → 0.2.0)
• fix: or bugfix: → Patch bump (0.1.0 → 0.1.1)
• breaking: or BREAKING: → Major bump (0.1.0 → 1.0.0)
• Other commits → Patch bump (default)

Manual Release (if needed)

If you need to manually trigger a release:

1. Go to Actions → Release workflow
2. Click "Run workflow"
3. Optionally select version type (or leave empty for auto-detect)
4. CI handles everything

Local Development Helpers

For local testing and preview:

# Check version status and suggested bump
pnpm version:info

# Auto-detect version bump (preview only)
pnpm version:auto

# Manual version bump (for testing)
pnpm version:patch
pnpm version:minor
pnpm version:major

# Update changelog manually (for testing)
pnpm changelog:update

Manual Publishing (if needed)

Only if you need to publish manually:

1. Set npm token:

   export NPM_TOKEN=your_npm_token

2. Build and publish:

   pnpm build:clean
   pnpm publish:npm

   Or use npm directly:

   npm publish --access public

Conventional Commits Format

Use this format for automatic version detection:

<type>(<scope>): <description>

Examples:

git commit -m "feat: add new card component"
git commit -m "fix(button): resolve hover state issue"
git commit -m "breaking: remove deprecated API"

Supported types:

• feat: / feature: - New features (minor bump)
• fix: / bugfix: - Bug fixes (patch bump)
• breaking: - Breaking changes (major bump)
• docs:, style:, refactor:, perf:, test:, chore:, build:, ci: - No version bump

Architecture

Package Structure

at-design/
├── src/
│   ├── components/        # All 29 UI components
│   ├── styles/           # CSS tokens, animations, base styles
│   │   ├── tokens.css    # Theme-agnostic CSS variables
│   │   ├── animations.css # Keyframe animations
│   │   └── base.css      # Base global styles
│   ├── utils/            # Utility functions
│   │   └── cn.ts        # Class name utility
│   └── index.ts          # Main export file
├── docs/
│   ├── COMPONENTS.md     # Component documentation
│   └── COMPONENT_CATEGORIES.md # Component categories
├── dist/                 # Build output (generated)
├── package.json
├── tsconfig.json
└── README.md

Design Principles

1. Theme-Agnostic: All styling uses CSS variables that can be overridden
2. Accessible: Built on Radix UI primitives for full accessibility
3. Composable: Components work together seamlessly
4. Type-Safe: Full TypeScript support with proper types
5. Apple-Inspired: Clean, minimal design with smooth animations

License

MIT

Links

• GitHub Repository: https://github.com/sayanmohsin/at-design
• npm Package (Private): @ancatag/at-design