Skip to main content
AppShell uses Tailwind CSS v4 for styling and provides a curated theme with Tailor Platform’s color palette and design tokens. All AppShell components are styled with Tailwind utility classes.

​
Quick start

Include AppShell’s theme in your global CSS file: 
/* src/global.css or src/index.css */
@import "@tailor-platform/app-shell/theme.css";
@import "tailwindcss";
The import order matters! Import AppShell’s theme before Tailwind to ensure proper CSS variable definitions.

​
Theme colors

After including the theme, AppShell’s custom colors are available as Tailwind utility classes: 
const MyComponent = () => {
  return (
    <div className="bg-muted text-muted-foreground">
      <h1 className="text-primary">Welcome</h1>
      <p className="text-foreground">Content goes here</p>
      <button className="bg-destructive text-destructive-foreground">
        Delete
      </button>
    </div>
  );
};

​
Available color tokens

AppShell’s theme provides semantic color tokens that adapt to light and dark modes:

​
Background and foreground

TokenPurposeLight ModeDark Mode
backgroundPage backgroundLight grayDark gray
foregroundPrimary textDark grayLight gray

​
Interactive elements

TokenPurpose
primaryPrimary actions and emphasis
primary-foregroundText on primary background
secondarySecondary actions
secondary-foregroundText on secondary background
accentHighlighted elements
accent-foregroundText on accent background

​
Muted and subtle

TokenPurpose
mutedSubtle backgrounds
muted-foregroundDe-emphasized text

​
Status and feedback

TokenPurpose
destructiveDangerous actions (delete, remove)
destructive-foregroundText on destructive background

​
Surfaces

TokenPurpose
cardCard backgrounds
card-foregroundText on cards
popoverPopover backgrounds
popover-foregroundText on popovers

​
Borders and inputs

TokenPurpose
borderBorder color
inputInput field borders
ringFocus ring color
TokenPurpose
sidebarSidebar background
sidebar-foregroundSidebar text
sidebar-primaryActive sidebar items
sidebar-primary-foregroundText on active items
sidebar-accentHover state
sidebar-accent-foregroundText on hover
sidebar-borderSidebar borders

​
Status colors

For status indicators and badges: 
--color-status-default: #737373;
--color-status-neutral: #0ea5e9;
--color-status-completed: #22c55e;
--color-status-attention: #f59e0b;
--color-status-danger: #ef4444;

​
Dark mode

AppShell includes built-in dark mode support. Toggle between themes using the useTheme hook: 
import { useTheme } from "@tailor-platform/app-shell";

const ThemeToggle = () => {
  const { theme, setTheme } = useTheme();
  
  return (
    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
      {theme === "dark" ? "☀️ Light" : "🌙 Dark"}
    </button>
  );
};

​
Available themes

  • "light" - Light theme
  • "dark" - Dark theme
  • "system" - Follow system preference (default)

​
Custom styling

​
Extending the theme

You can extend AppShell’s theme with your own colors: 
/* src/global.css */
@import "@tailor-platform/app-shell/theme.css";
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --color-brand-foreground: #ffffff;
}
Use in components: 
<button className="bg-brand text-brand-foreground">
  Brand Action
</button>

​
Override default colors

To customize AppShell’s default colors, override the CSS variables: 
@import "@tailor-platform/app-shell/theme.css";

:root {
  --primary: rgba(59, 130, 246, 1); /* Custom blue */
  --primary-foreground: rgba(255, 255, 255, 1);
}

.dark {
  --primary: rgba(96, 165, 250, 1); /* Lighter blue for dark mode */
  --primary-foreground: rgba(23, 23, 23, 1);
}

@import "tailwindcss";

​
AppShell component styling

​
Class prefix

AppShell components use a astw: prefix (AppShell TailWind) to avoid class name conflicts: 
// AppShell internal component
<div className="astw:flex astw:items-center astw:gap-4">
  {/* Content */}
</div>
You don’t need to use the astw: prefix in your own components—it’s only for AppShell’s internal components.

​
Why the prefix?

Tailwind generates separate stylesheets for AppShell components and your application. The prefix prevents style definition order conflicts between these two stylesheets.

​
Styling AppShell components

Many AppShell components accept a className prop for customization: 
import { SidebarLayout } from "@tailor-platform/app-shell";

<SidebarLayout 
  className="bg-background border-r border-border"
  sidebar={<MySidebar />}
/>

​
Typography

AppShell doesn’t enforce specific typography styles. Use Tailwind’s typography utilities: 
<div>
  <h1 className="text-4xl font-bold text-foreground">Page Title</h1>
  <p className="text-base text-muted-foreground">Subtitle text</p>
</div>

​
Responsive design

Use Tailwind’s responsive utilities with AppShell: 
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Responsive grid */}
</div>

​
Radius tokens

AppShell provides border radius tokens: 
--radius-sm: calc(var(--radius) - 4px);  /* Small radius */
--radius-md: calc(var(--radius) - 2px);  /* Medium radius */
--radius-lg: var(--radius);               /* Large radius (default: 0.625rem) */
--radius-xl: calc(var(--radius) + 4px);  /* Extra large radius */
Use in Tailwind: 
<div className="rounded-lg"> {/* Uses --radius-lg */}
  <div className="rounded-md"> {/* Uses --radius-md */}
    Content
  </div>
</div>

​
Example: Custom component

Combining AppShell’s theme tokens: 
const StatusCard = ({ status, children }: { status: string; children: React.ReactNode }) => {
  const statusColors = {
    success: "bg-status-completed text-white",
    warning: "bg-status-attention text-white",
    error: "bg-status-danger text-white",
    info: "bg-status-neutral text-white",
  };
  
  return (
    <div className={`rounded-lg p-4 ${statusColors[status]}`}>
      {children}
    </div>
  );
};

​
Best practices

Use semantic tokens

Prefer text-foreground over text-gray-900 for theme consistency

Respect dark mode

Test components in both light and dark themes

Leverage Tailwind

Use Tailwind utilities instead of custom CSS when possible

Extend thoughtfully

Add custom colors only when semantic tokens don’t fit

​
Omitting the theme

If you omit @import "@tailor-platform/app-shell/theme.css", most of the UI will still work, but you’ll lose:
  • Tailor Platform’s curated color palette
  • Sidebar-specific color tokens
  • Status color tokens
  • Consistent dark mode colors
While optional, including the theme is strongly recommended for a cohesive design experience.

Tailwind CSS

Official Tailwind CSS documentation

Components

Explore AppShell’s pre-built components

Build docs developers (and LLMs) love

Get started for freeTalk to us