From b84698e17c6fa3136400b9f48cce466d3ade4538 Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Sun, 1 Feb 2026 11:53:36 -0600 Subject: [PATCH 1/8] docs: create docs for apsara tokens --- apps/www/src/content/docs/meta.json | 2 +- .../src/content/docs/theme/colors/index.mdx | 535 ++++++++++++++++++ .../src/content/docs/theme/effects/index.mdx | 180 ++++++ apps/www/src/content/docs/theme/meta.json | 4 + .../src/content/docs/theme/overview/index.mdx | 270 +++++++++ .../src/content/docs/theme/overview/props.ts | 93 +++ .../src/content/docs/theme/radius/index.mdx | 219 +++++++ .../src/content/docs/theme/spacing/index.mdx | 183 ++++++ .../content/docs/theme/typography/index.mdx | 461 +++++++++++++++ 9 files changed, 1946 insertions(+), 1 deletion(-) create mode 100644 apps/www/src/content/docs/theme/colors/index.mdx create mode 100644 apps/www/src/content/docs/theme/effects/index.mdx create mode 100644 apps/www/src/content/docs/theme/meta.json create mode 100644 apps/www/src/content/docs/theme/overview/index.mdx create mode 100644 apps/www/src/content/docs/theme/overview/props.ts create mode 100644 apps/www/src/content/docs/theme/radius/index.mdx create mode 100644 apps/www/src/content/docs/theme/spacing/index.mdx create mode 100644 apps/www/src/content/docs/theme/typography/index.mdx diff --git a/apps/www/src/content/docs/meta.json b/apps/www/src/content/docs/meta.json index 617294532..8267e5fcb 100644 --- a/apps/www/src/content/docs/meta.json +++ b/apps/www/src/content/docs/meta.json @@ -1,3 +1,3 @@ { - "pages": ["(overview)", "components"] + "pages": ["(overview)", "theme", "components"] } diff --git a/apps/www/src/content/docs/theme/colors/index.mdx b/apps/www/src/content/docs/theme/colors/index.mdx new file mode 100644 index 000000000..451f2f6c7 --- /dev/null +++ b/apps/www/src/content/docs/theme/colors/index.mdx @@ -0,0 +1,535 @@ +--- +title: Colors +description: Overview of the color system and semantic color tokens in Apsara. +--- + +import { Table } from "@raystack/apsara"; + +Apsara uses a semantic color system that provides meaningful, context-aware colors for your interface. Colors are organized by their purpose rather than their appearance, making it easy to maintain consistency and support theming. + +## Foreground Colors + +Foreground colors are used for text, icons, and other content elements. + +### Base Foreground + + + + + Token + Description + + + + + --rs-color-foreground-base-primary + Primary text color for headings and important content + + + --rs-color-foreground-base-secondary + Secondary text color for supporting content + + + --rs-color-foreground-base-tertiary + Tertiary text color for muted or placeholder content + + + --rs-color-foreground-base-emphasis + High contrast text for emphasis on colored backgrounds + + +
+ +### Semantic Foreground + + + + + Token + Description + + + + + --rs-color-foreground-accent-primary + Accent color for interactive elements and links + + + --rs-color-foreground-accent-primary-hover + Hover state for accent foreground + + + --rs-color-foreground-accent-emphasis + Text on accent emphasis backgrounds + + + --rs-color-foreground-danger-primary + Error and destructive action text + + + --rs-color-foreground-danger-primary-hover + Hover state for danger foreground + + + --rs-color-foreground-danger-emphasis + Text on danger emphasis backgrounds + + + --rs-color-foreground-attention-primary + Warning and attention text + + + --rs-color-foreground-attention-primary-hover + Hover state for attention foreground + + + --rs-color-foreground-attention-emphasis + Text on attention emphasis backgrounds + + + --rs-color-foreground-success-primary + Success and positive action text + + + --rs-color-foreground-success-primary-hover + Hover state for success foreground + + + --rs-color-foreground-success-emphasis + Text on success emphasis backgrounds + + +
+ +## Background Colors + +Background colors define surfaces and containers in your interface. + +### Base Background + + + + + Token + Description + + + + + --rs-color-background-base-primary + Primary background for main content areas + + + --rs-color-background-base-primary-hover + Hover state for primary background + + + --rs-color-background-base-secondary + Secondary background for cards and panels + + + --rs-color-background-neutral-primary + Neutral background for subtle elements + + + --rs-color-background-neutral-secondary + Secondary neutral background + + + --rs-color-background-neutral-secondary-hover + Hover state for secondary neutral background + + + --rs-color-background-neutral-tertiary + Tertiary neutral background + + + --rs-color-background-neutral-tertiary-hover + Hover state for tertiary neutral background + + + --rs-color-background-neutral-emphasis + High contrast neutral background + + +
+ +### Semantic Background + + + + + Token + Description + + + + + --rs-color-background-accent-primary + Subtle accent background for highlights + + + --rs-color-background-accent-emphasis + Strong accent background for buttons and CTAs + + + --rs-color-background-accent-emphasis-hover + Hover state for accent emphasis background + + + --rs-color-background-danger-primary + Subtle danger background for error states + + + --rs-color-background-danger-emphasis + Strong danger background for destructive actions + + + --rs-color-background-danger-emphasis-hover + Hover state for danger emphasis background + + + --rs-color-background-attention-primary + Subtle attention background for warnings + + + --rs-color-background-attention-emphasis + Strong attention background + + + --rs-color-background-attention-emphasis-hover + Hover state for attention emphasis background + + + --rs-color-background-success-primary + Subtle success background for positive states + + + --rs-color-background-success-emphasis + Strong success background + + + --rs-color-background-success-emphasis-hover + Hover state for success emphasis background + + +
+ +## Border Colors + +Border colors define boundaries and separators. + + + + + Token + Description + + + + + --rs-color-border-base-primary + Primary border for subtle boundaries + + + --rs-color-border-base-secondary + Secondary border for dividers + + + --rs-color-border-base-tertiary + Tertiary border for inputs and cards + + + --rs-color-border-base-tertiary-hover + Hover state for tertiary border + + + --rs-color-border-base-focus + Focus ring for interactive elements + + + --rs-color-border-base-emphasis + High contrast border for emphasis + + + --rs-color-border-accent-primary + Accent border for highlights + + + --rs-color-border-accent-emphasis + Strong accent border + + + --rs-color-border-accent-emphasis-hover + Hover state for accent emphasis border + + + --rs-color-border-danger-primary + Danger border for error states + + + --rs-color-border-danger-emphasis + Strong danger border + + + --rs-color-border-danger-emphasis-hover + Hover state for danger emphasis border + + + --rs-color-border-attention-primary + Attention border for warnings + + + --rs-color-border-attention-emphasis + Strong attention border + + + --rs-color-border-attention-emphasis-hover + Hover state for attention emphasis border + + + --rs-color-border-success-primary + Success border for positive states + + + --rs-color-border-success-emphasis + Strong success border + + + --rs-color-border-success-emphasis-hover + Hover state for success emphasis border + + +
+ +## Overlay Colors + +Overlay colors are used for modals, tooltips, and layered elements. + + + + + Token + Opacity + + + + + --rs-color-overlay-base-primary + Default overlay + + + --rs-color-overlay-black-a1 + 5% + + + --rs-color-overlay-black-a2 + 10% + + + --rs-color-overlay-black-a3 + 15% + + + --rs-color-overlay-black-a4 + 20% + + + --rs-color-overlay-black-a5 + 30% + + + --rs-color-overlay-black-a6 + 40% + + + --rs-color-overlay-black-a7 + 50% + + + --rs-color-overlay-black-a8 + 60% + + + --rs-color-overlay-black-a9 + 70% + + + --rs-color-overlay-black-a10 + 80% + + + --rs-color-overlay-black-a11 + 90% + + + --rs-color-overlay-black-a12 + 95% + + + --rs-color-overlay-white-a1 + 5% + + + --rs-color-overlay-white-a2 + 10% + + + --rs-color-overlay-white-a3 + 15% + + + --rs-color-overlay-white-a4 + 20% + + + --rs-color-overlay-white-a5 + 30% + + + --rs-color-overlay-white-a6 + 40% + + + --rs-color-overlay-white-a7 + 50% + + + --rs-color-overlay-white-a8 + 60% + + + --rs-color-overlay-white-a9 + 70% + + + --rs-color-overlay-white-a10 + 80% + + + --rs-color-overlay-white-a11 + 90% + + + --rs-color-overlay-white-a12 + 95% + + +
+ +## Visualization Colors + +A palette of colors designed for data visualization, charts, and graphs. + + + + + Color + Tokens + + + + + Sky + --rs-color-viz-sky-6, --rs-color-viz-sky-8, --rs-color-viz-sky-9, --rs-color-viz-sky-11 + + + Mint + --rs-color-viz-mint-6, --rs-color-viz-mint-8, --rs-color-viz-mint-9, --rs-color-viz-mint-11 + + + Lime + --rs-color-viz-lime-6, --rs-color-viz-lime-8, --rs-color-viz-lime-9, --rs-color-viz-lime-11 + + + Grass + --rs-color-viz-grass-6, --rs-color-viz-grass-8, --rs-color-viz-grass-9, --rs-color-viz-grass-11 + + + Green + --rs-color-viz-green-6, --rs-color-viz-green-8, --rs-color-viz-green-9, --rs-color-viz-green-11 + + + Jade + --rs-color-viz-jade-6, --rs-color-viz-jade-8, --rs-color-viz-jade-9, --rs-color-viz-jade-11 + + + Cyan + --rs-color-viz-cyan-6, --rs-color-viz-cyan-8, --rs-color-viz-cyan-9, --rs-color-viz-cyan-11 + + + Blue + --rs-color-viz-blue-6, --rs-color-viz-blue-8, --rs-color-viz-blue-9, --rs-color-viz-blue-11 + + + Iris + --rs-color-viz-iris-6, --rs-color-viz-iris-8, --rs-color-viz-iris-9, --rs-color-viz-iris-11 + + + Purple + --rs-color-viz-purple-6, --rs-color-viz-purple-8, --rs-color-viz-purple-9, --rs-color-viz-purple-11 + + + Pink + --rs-color-viz-pink-6, --rs-color-viz-pink-8, --rs-color-viz-pink-9, --rs-color-viz-pink-11 + + + Crimson + --rs-color-viz-crimson-6, --rs-color-viz-crimson-8, --rs-color-viz-crimson-9, --rs-color-viz-crimson-11 + + + Orange + --rs-color-viz-orange-6, --rs-color-viz-orange-8, --rs-color-viz-orange-9, --rs-color-viz-orange-11 + + + Gold + --rs-color-viz-gold-6, --rs-color-viz-gold-8, --rs-color-viz-gold-9, --rs-color-viz-gold-11 + + +
+ +## Usage + +```css +/* Text colors */ +.heading { + color: var(--rs-color-foreground-base-primary); +} + +.description { + color: var(--rs-color-foreground-base-secondary); +} + +/* Background colors */ +.card { + background-color: var(--rs-color-background-base-secondary); +} + +.button-primary { + background-color: var(--rs-color-background-accent-emphasis); + color: var(--rs-color-foreground-accent-emphasis); +} + +/* Border colors */ +.input { + border: 1px solid var(--rs-color-border-base-tertiary); +} + +.input:focus { + border-color: var(--rs-color-border-accent-emphasis); +} + +/* Semantic states */ +.error { + color: var(--rs-color-foreground-danger-primary); + background-color: var(--rs-color-background-danger-primary); + border-color: var(--rs-color-border-danger-primary); +} +``` + +## Best Practices + +- **Use semantic tokens** - Prefer semantic color tokens over raw color values for consistency and theming support +- **Match foreground with background** - Use corresponding foreground colors when placing text on semantic backgrounds (e.g., `foreground-accent-emphasis` on `background-accent-emphasis`) +- **Respect color hierarchy** - Use primary colors for main content, secondary for supporting content, and tertiary for subtle elements +- **Test in both themes** - Ensure your color choices work well in both light and dark modes diff --git a/apps/www/src/content/docs/theme/effects/index.mdx b/apps/www/src/content/docs/theme/effects/index.mdx new file mode 100644 index 000000000..b0814048e --- /dev/null +++ b/apps/www/src/content/docs/theme/effects/index.mdx @@ -0,0 +1,180 @@ +--- +title: Effects +description: Overview of shadow and blur effect tokens in Apsara. +--- + +import { Table } from "@raystack/apsara"; + +Effects add depth and visual hierarchy to your interface through shadows and blur. Apsara provides semantic effect tokens that work consistently across light and dark themes. + +## Shadows + +Shadow tokens create elevation and depth, helping users understand the layering of interface elements. + + + + + Token + Description + Use Case + + + + + --rs-shadow-feather + Subtle, minimal shadow + Cards, subtle elevation + + + --rs-shadow-soft + Soft, gentle shadow + Buttons, interactive elements + + + --rs-shadow-lifted + Noticeable elevation + Dropdowns, popovers + + + --rs-shadow-floating + Strong floating effect + Modals, dialogs, tooltips + + + --rs-shadow-inset + Inner shadow + Pressed states, inputs + + +
+ +## Blur Effects + +Blur tokens are used for backdrop effects and creating depth through transparency. + + + + + Token + Value + Use Case + + + + + --rs-blur-sm + blur(0.5px) + Subtle blur effect + + + --rs-blur-md + blur(1px) + Medium blur effect + + + --rs-blur-lg + blur(2px) + Noticeable blur effect + + + --rs-blur-xl + blur(4px) + Strong blur for overlays + + +
+ +## Usage + +### Shadows + +```css +/* Card with subtle shadow */ +.card { + box-shadow: var(--rs-shadow-feather); +} + +/* Card on hover with lifted effect */ +.card:hover { + box-shadow: var(--rs-shadow-lifted); +} + +/* Dropdown menu */ +.dropdown { + box-shadow: var(--rs-shadow-lifted); +} + +/* Modal dialog */ +.modal { + box-shadow: var(--rs-shadow-floating); +} + +/* Pressed button state */ +.button:active { + box-shadow: var(--rs-shadow-inset); +} +``` + +### Blur Effects + +```css +/* Frosted glass effect */ +.glass { + backdrop-filter: var(--rs-blur-lg); + background-color: var(--rs-color-overlay-white-a4); +} + +/* Subtle background blur */ +.overlay { + backdrop-filter: var(--rs-blur-xl); +} +``` + +## Elevation Hierarchy + +Use shadows to establish visual hierarchy and indicate interactive states: + + + + + Level + Shadow + Examples + + + + + Level 0 + None + Flat surfaces, backgrounds + + + Level 1 + --rs-shadow-feather + Cards, panels + + + Level 2 + --rs-shadow-soft + Buttons, interactive cards + + + Level 3 + --rs-shadow-lifted + Dropdowns, popovers, hover states + + + Level 4 + --rs-shadow-floating + Modals, dialogs, toasts + + +
+ +## Best Practices + +- **Use shadows sparingly** - Too many shadows can make interfaces feel cluttered +- **Match elevation to importance** - Higher elevation shadows for more prominent elements +- **Consider theme context** - Shadows are automatically adjusted for dark theme +- **Combine with blur** - Use blur effects with overlays for a modern frosted glass aesthetic +- **Animate transitions** - Smooth shadow transitions on hover create polished interactions diff --git a/apps/www/src/content/docs/theme/meta.json b/apps/www/src/content/docs/theme/meta.json new file mode 100644 index 000000000..0b2d1fb8b --- /dev/null +++ b/apps/www/src/content/docs/theme/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Theme", + "pages": ["overview", "colors", "typography", "spacing", "radius", "effects"] +} diff --git a/apps/www/src/content/docs/theme/overview/index.mdx b/apps/www/src/content/docs/theme/overview/index.mdx new file mode 100644 index 000000000..e632d7acd --- /dev/null +++ b/apps/www/src/content/docs/theme/overview/index.mdx @@ -0,0 +1,270 @@ +--- +title: Overview +description: Understanding the Apsara theming system and ThemeProvider. +--- + +import { Table } from "@raystack/apsara"; + +Apsara provides a flexible theming system that supports light and dark modes, multiple accent colors, gray color variants, and style presets. The `ThemeProvider` component manages theme state and applies the appropriate CSS variables to your application. + +## Installation + +Wrap your application with the `ThemeProvider` component: + +```tsx +import { ThemeProvider } from "@raystack/apsara"; + +function App() { + return ( + + {/* Your application */} + + ); +} +``` + +## Theme Modes + +Apsara supports three theme modes: + + + + + Mode + Description + + + + + light + Light color scheme + + + dark + Dark color scheme + + + system + Follows the user's system preference + + +
+ +## Style Variants + +Style variants affect the overall visual appearance, including border radius and typography: + + + + + Style + Description + + + + + modern + Sharp corners, Inter font family (default) + + + traditional + Softer, rounded corners, Lora/Josefin Sans fonts + + +
+ +## Accent Colors + +Accent colors define the primary brand color used throughout the interface: + + + + + Color + Description + + + + + indigo + Blue-violet accent (default) + + + orange + Warm orange accent + + + mint + Fresh mint/teal accent + + +
+ +## Gray Colors + +Gray color variants affect neutral tones throughout the interface: + + + + + Color + Description + + + + + gray + Pure neutral gray (default) + + + mauve + Warm gray with purple undertone + + + slate + Cool gray with blue undertone + + +
+ +## ThemeProvider Props + + + +## useTheme Hook + +Access and control the current theme using the `useTheme` hook: + +```tsx +import { useTheme } from "@raystack/apsara"; + +function ThemeToggle() { + const { theme, setTheme, resolvedTheme, systemTheme } = useTheme(); + + return ( + + ); +} +``` + +### useTheme Return Values + + + +## Examples + +### Basic Setup + +```tsx +import { ThemeProvider } from "@raystack/apsara"; + +function App() { + return ( + + + + ); +} +``` + +### Custom Accent Color + +```tsx + + + +``` + +### Traditional Style + +```tsx + + + +``` + +### Force Dark Mode + +```tsx + + + +``` + +### Complete Configuration + +```tsx + + + +``` + +## HTML Attributes + +The ThemeProvider sets the following attributes on the document element: + + + + + Attribute + Example Value + Description + + + + + data-theme + "light" or "dark" + Current color scheme + + + data-style + "modern" or "traditional" + Visual style variant + + + data-accent-color + "indigo" + Accent color + + + data-gray-color + "gray" + Gray color variant + + +
+ +## Avoiding Flash + +The ThemeProvider includes an inline script that runs before React hydration to prevent flash of incorrect theme. This ensures the correct theme is applied immediately on page load. + +For SSR frameworks, ensure the ThemeProvider is included in your root layout: + +```tsx +// Next.js App Router example +// app/layout.tsx +import { ThemeProvider } from "@raystack/apsara"; + +export default function RootLayout({ children }) { + return ( + + + {children} + + + ); +} +``` + +The `suppressHydrationWarning` is needed because the theme script modifies the HTML element before React hydrates. diff --git a/apps/www/src/content/docs/theme/overview/props.ts b/apps/www/src/content/docs/theme/overview/props.ts new file mode 100644 index 000000000..e76751474 --- /dev/null +++ b/apps/www/src/content/docs/theme/overview/props.ts @@ -0,0 +1,93 @@ +export type ThemeProviderProps = { + /** + * Default theme on first load + * @defaultValue "system" + */ + defaultTheme?: string; + + /** + * List of available theme names + * @defaultValue ["light", "dark"] + */ + themes?: string[]; + + /** Force a specific theme, ignoring user preference */ + forcedTheme?: string; + + /** + * Enable system theme detection + * @defaultValue true + */ + enableSystem?: boolean; + + /** + * localStorage key for persisting theme + * @defaultValue "theme" + */ + storageKey?: string; + + /** + * HTML attribute to set on document element + * @defaultValue "data-theme" + */ + attribute?: string | 'class'; + + /** + * Visual style variant + * @defaultValue "modern" + */ + style?: 'modern' | 'traditional'; + + /** + * Primary accent color + * @defaultValue "indigo" + */ + accentColor?: 'indigo' | 'orange' | 'mint'; + + /** + * Neutral gray color variant + * @defaultValue "gray" + */ + grayColor?: 'gray' | 'mauve' | 'slate'; + + /** + * Disable CSS transitions when switching themes + * @defaultValue false + */ + disableTransitionOnChange?: boolean; + + /** + * Set color-scheme CSS property for native elements + * @defaultValue true + */ + enableColorScheme?: boolean; + + /** Nonce string for CSP headers */ + nonce?: string; + + /** Mapping of theme name to HTML attribute value */ + value?: { [themeName: string]: string }; + + /** React children */ + children?: React.ReactNode; +}; + +export type UseThemeProps = { + /** Current theme name ("light", "dark", or "system") */ + theme?: string; + + /** Function to change the theme */ + setTheme: (theme: string) => void; + + /** Resolved theme ("light" or "dark"), useful when theme is "system" */ + resolvedTheme?: string; + + /** System preference, regardless of current theme */ + systemTheme?: 'light' | 'dark'; + + /** List of all available themes */ + themes: string[]; + + /** Forced theme if set, otherwise undefined */ + forcedTheme?: string; +}; diff --git a/apps/www/src/content/docs/theme/radius/index.mdx b/apps/www/src/content/docs/theme/radius/index.mdx new file mode 100644 index 000000000..5df2ef3be --- /dev/null +++ b/apps/www/src/content/docs/theme/radius/index.mdx @@ -0,0 +1,219 @@ +--- +title: Radius +description: Overview of the border radius scale and style variants in Apsara. +--- + +import { Table } from "@raystack/apsara"; + +Border radius tokens control the roundness of corners throughout your interface. Apsara provides a consistent radius scale with support for different style variants. + +## Radius Scale + +The radius scale provides 7 tokens for different levels of roundness, from subtle to fully circular. + +### Modern Style (Default) + + + + + Token + Value + Use Case + + + + + --rs-radius-1 + 2px + Subtle rounding for small elements + + + --rs-radius-2 + 4px + Badges, chips, small buttons + + + --rs-radius-3 + 6px + Inputs, buttons, cards + + + --rs-radius-4 + 8px + Modals, dialogs, larger cards + + + --rs-radius-5 + 12px + Large containers, panels + + + --rs-radius-6 + 16px + Extra large containers + + + --rs-radius-full + 800px + Pills, circular elements, avatars + + +
+ +### Traditional Style + +When using `data-style="traditional"`, the radius values increase for a softer, more rounded appearance. + + + + + Token + Value + Use Case + + + + + --rs-radius-1 + 8px + Subtle rounding for small elements + + + --rs-radius-2 + 16px + Badges, chips, small buttons + + + --rs-radius-3 + 20px + Inputs, buttons, cards + + + --rs-radius-4 + 24px + Modals, dialogs, larger cards + + + --rs-radius-5 + 32px + Large containers, panels + + + --rs-radius-6 + 40px + Extra large containers + + + --rs-radius-full + 1600px + Pills, circular elements, avatars + + +
+ +## Style Comparison + + + + + Token + Modern + Traditional + + + + + --rs-radius-1 + 2px + 8px + + + --rs-radius-2 + 4px + 16px + + + --rs-radius-3 + 6px + 20px + + + --rs-radius-4 + 8px + 24px + + + --rs-radius-5 + 12px + 32px + + + --rs-radius-6 + 16px + 40px + + + --rs-radius-full + 800px + 1600px + + +
+ +## Usage + +```css +/* Buttons */ +.button { + border-radius: var(--rs-radius-3); +} + +/* Cards */ +.card { + border-radius: var(--rs-radius-4); +} + +/* Badges and chips */ +.badge { + border-radius: var(--rs-radius-2); +} + +/* Pills and tags */ +.pill { + border-radius: var(--rs-radius-full); +} + +/* Avatar */ +.avatar { + border-radius: var(--rs-radius-full); +} + +/* Input fields */ +.input { + border-radius: var(--rs-radius-3); +} + +/* Modal */ +.modal { + border-radius: var(--rs-radius-5); +} +``` + +## Enabling Style Variants + +To switch between modern and traditional styles, set the `data-style` attribute on your root element: + +```html + + + + + +``` + +## Best Practices + +- **Be consistent** - Use the same radius token for similar elements throughout your application +- **Match element size** - Use smaller radius values for smaller elements, larger values for containers +- **Use radius-full for circles** - When you need perfectly circular elements, use `--rs-radius-full` +- **Consider style context** - Choose modern for sharp, contemporary designs; traditional for softer, friendly aesthetics diff --git a/apps/www/src/content/docs/theme/spacing/index.mdx b/apps/www/src/content/docs/theme/spacing/index.mdx new file mode 100644 index 000000000..78aa1c954 --- /dev/null +++ b/apps/www/src/content/docs/theme/spacing/index.mdx @@ -0,0 +1,183 @@ +--- +title: Spacing +description: Overview of the space scale and spacing tokens in Apsara. +--- + +import { Table } from "@raystack/apsara"; + +Consistent spacing creates visual rhythm and hierarchy in your interface. Apsara provides a comprehensive spacing scale through CSS custom properties that you can use throughout your application. + +## Scale + +Spacing values are derived from a 17-step scale, which provides fine-grained control over layout spacing. The scale starts at 2px and progressively increases to 120px, allowing for both tight and spacious layouts. + + + + + Token + Value + Use Case + + + + + --rs-space-1 + 2px + Minimal spacing, icon gaps + + + --rs-space-2 + 4px + Tight spacing, small gaps + + + --rs-space-3 + 8px + Compact padding, inline spacing + + + --rs-space-4 + 12px + Standard small padding + + + --rs-space-5 + 16px + Default padding, common gaps + + + --rs-space-6 + 20px + Medium padding + + + --rs-space-7 + 24px + Comfortable spacing + + + --rs-space-8 + 28px + Generous padding + + + --rs-space-9 + 32px + Large spacing + + + --rs-space-10 + 40px + Section gaps + + + --rs-space-11 + 48px + Large section spacing + + + --rs-space-12 + 56px + Extra large spacing + + + --rs-space-13 + 64px + Major divisions + + + --rs-space-14 + 72px + Layout spacing + + + --rs-space-15 + 80px + Page sections + + + --rs-space-16 + 96px + Large page sections + + + --rs-space-17 + 120px + Maximum spacing + + +
+ +## Tokens + +Space scale tokens can be accessed using CSS variables. Use these tokens to style your custom components, ensuring they are consistent with the rest of your theme. + +```css +/* Space scale */ +var(--rs-space-1); /* 2px */ +var(--rs-space-2); /* 4px */ +var(--rs-space-3); /* 8px */ +var(--rs-space-4); /* 12px */ +var(--rs-space-5); /* 16px */ +var(--rs-space-6); /* 20px */ +var(--rs-space-7); /* 24px */ +var(--rs-space-8); /* 28px */ +var(--rs-space-9); /* 32px */ +var(--rs-space-10); /* 40px */ +var(--rs-space-11); /* 48px */ +var(--rs-space-12); /* 56px */ +var(--rs-space-13); /* 64px */ +var(--rs-space-14); /* 72px */ +var(--rs-space-15); /* 80px */ +var(--rs-space-16); /* 96px */ +var(--rs-space-17); /* 120px */ +``` + +## Semantic Groupings + +The spacing scale can be organized into semantic groups for easier selection: + + + + + Group + Tokens + Values + Purpose + + + + + Compact + 1-3 + 2px - 8px + Tight UI elements, icon spacing + + + Comfortable + 4-7 + 12px - 24px + Standard component padding + + + Spacious + 8-11 + 28px - 48px + Section spacing, larger gaps + + + Layout + 12-17 + 56px - 120px + Page sections, major divisions + + +
+ +## Best Practices + +- **Use smaller values (1-5)** for internal component spacing like padding and gaps between inline elements +- **Use medium values (5-9)** for spacing between related components and within sections +- **Use larger values (10-17)** for spacing between sections and major layout divisions +- **Be consistent** - use the same spacing token for similar contexts throughout your application +- **Avoid mixing** pixel values with spacing tokens to maintain consistency diff --git a/apps/www/src/content/docs/theme/typography/index.mdx b/apps/www/src/content/docs/theme/typography/index.mdx new file mode 100644 index 000000000..a235b9698 --- /dev/null +++ b/apps/www/src/content/docs/theme/typography/index.mdx @@ -0,0 +1,461 @@ +--- +title: Typography +description: Overview of the typography system and text tokens in Apsara. +--- + +import { Table } from "@raystack/apsara"; + +Apsara provides a comprehensive typography system with carefully crafted font families, sizes, weights, and spacing to ensure readable and consistent text across your application. + +## Font Families + +Apsara includes three font family categories for different use cases. + + + + + Token + Default Value + Use Case + + + + + --rs-font-title + Inter, sans-serif + Headings and titles + + + --rs-font-body + Inter, sans-serif + Body text and paragraphs + + + --rs-font-mono + Menlo, JetBrains Mono, monospace + Code and technical content + + +
+ +### Available Fonts + + + + + Token + Font + + + + + --rs-font-inter + Inter + + + --rs-font-lora + Lora + + + --rs-font-josefin-sans + Josefin Sans + + + --rs-font-jetbrains-mono + JetBrains Mono + + + --rs-font-menlo + Menlo + + +
+ +## Font Weights + + + + + Token + Value + Use Case + + + + + --rs-font-weight-regular + 400 + Body text, descriptions + + + --rs-font-weight-medium + 500 + Headings, labels, emphasis + + +
+ +## Body Text + +Font sizes, line heights, and letter spacing for body content. + +### Font Sizes + + + + + Token + Size + Use Case + + + + + --rs-font-size-micro + 10px + Fine print, timestamps + + + --rs-font-size-mini + 11px + Captions, badges + + + --rs-font-size-small + 12px + Secondary text, labels + + + --rs-font-size-regular + 14px + Default body text + + + --rs-font-size-large + 16px + Large body text, introductions + + +
+ +### Line Heights + + + + + Token + Value + + + + + --rs-line-height-micro + 12px + + + --rs-line-height-mini + 16px + + + --rs-line-height-small + 16px + + + --rs-line-height-regular + 20px + + + --rs-line-height-large + 24px + + +
+ +### Letter Spacing + + + + + Token + Value + + + + + --rs-letter-spacing-micro + 0.5px + + + --rs-letter-spacing-mini + 0.5px + + + --rs-letter-spacing-small + 0.4px + + + --rs-letter-spacing-regular + 0.25px + + + --rs-letter-spacing-large + 0.5px + + +
+ +## Title Text + +Font sizes, line heights, and letter spacing for headings and titles. + +### Font Sizes + + + + + Token + Size + Use Case + + + + + --rs-font-size-t1 + 20px + Small headings (h4) + + + --rs-font-size-t2 + 24px + Section headings (h3) + + + --rs-font-size-t3 + 28px + Page headings (h2) + + + --rs-font-size-t4 + 32px + Main titles (h1) + + +
+ +### Line Heights + + + + + Token + Value + + + + + --rs-line-height-t1 + 24px + + + --rs-line-height-t2 + 32px + + + --rs-line-height-t3 + 36px + + + --rs-line-height-t4 + 40px + + +
+ +### Letter Spacing + + + + + Token + Value + + + + + --rs-letter-spacing-t1 + 0 + + + --rs-letter-spacing-t2 + 0 + + + --rs-letter-spacing-t3 + 0 + + + --rs-letter-spacing-t4 + 0 + + +
+ +## Monospace Text + +Font sizes, line heights, and letter spacing for code and technical content. + +### Font Sizes + + + + + Token + Size + + + + + --rs-font-size-mono-mini + 11px + + + --rs-font-size-mono-small + 12px + + + --rs-font-size-mono-regular + 14px + + + --rs-font-size-mono-large + 16px + + +
+ +### Line Heights + + + + + Token + Value + + + + + --rs-line-height-mono-mini + 16px + + + --rs-line-height-mono-small + 16px + + + --rs-line-height-mono-regular + 20px + + + --rs-line-height-mono-large + 24px + + +
+ +### Letter Spacing + + + + + Token + Value + + + + + --rs-letter-spacing-mono-mini + 0px + + + --rs-letter-spacing-mono-small + 0px + + + --rs-letter-spacing-mono-regular + 0px + + + --rs-letter-spacing-mono-large + 0px + + +
+ +## Style Variants + +Apsara supports different style variants that change typography to match your design preference. + +### Traditional Style + +When using `data-style="traditional"`, the font families change to: + + + + + Token + Traditional Value + + + + + --rs-font-title + Lora, serif + + + --rs-font-body + Josefin Sans, sans-serif + + +
+ +## Usage + +```css +/* Body text */ +.paragraph { + font-family: var(--rs-font-body); + font-size: var(--rs-font-size-regular); + font-weight: var(--rs-font-weight-regular); + line-height: var(--rs-line-height-regular); + letter-spacing: var(--rs-letter-spacing-regular); +} + +/* Headings */ +.heading { + font-family: var(--rs-font-title); + font-size: var(--rs-font-size-t2); + font-weight: var(--rs-font-weight-medium); + line-height: var(--rs-line-height-t2); +} + +/* Code */ +.code { + font-family: var(--rs-font-mono); + font-size: var(--rs-font-size-mono-small); + line-height: var(--rs-line-height-mono-small); +} + +/* Small text */ +.caption { + font-size: var(--rs-font-size-small); + line-height: var(--rs-line-height-small); + letter-spacing: var(--rs-letter-spacing-small); +} +``` + +## Best Practices + +- **Use semantic sizing** - Match font sizes to their intended purpose (body, titles, code) +- **Pair sizes with line heights** - Always use the corresponding line height token for each font size +- **Maintain hierarchy** - Use font weights and sizes to establish clear visual hierarchy +- **Consider readability** - Use appropriate letter spacing for different text sizes From b5b8f18935f546571abaaa2e0141062ccaca615d Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Sun, 1 Feb 2026 15:44:50 -0600 Subject: [PATCH 2/8] docs: add TokenTable component for token documentation Add a reusable TokenTable component with visual previews for different token types (color, spacing, radius, shadow, blur) and copy-to-clipboard functionality. Update all theme documentation to use the new component. --- .../www/src/components/mdx/mdx-components.tsx | 4 + apps/www/src/components/tokentable/index.ts | 6 + .../tokentable/tokentable.module.css | 255 ++++++++ .../src/components/tokentable/tokentable.tsx | 174 ++++++ .../src/content/docs/theme/colors/index.mdx | 577 ++++-------------- .../src/content/docs/theme/effects/index.mdx | 134 +--- .../src/content/docs/theme/overview/index.mdx | 152 ++--- .../src/content/docs/theme/radius/index.mdx | 175 ++---- .../src/content/docs/theme/spacing/index.mdx | 164 +---- .../content/docs/theme/typography/index.mdx | 470 ++++---------- 10 files changed, 813 insertions(+), 1298 deletions(-) create mode 100644 apps/www/src/components/tokentable/index.ts create mode 100644 apps/www/src/components/tokentable/tokentable.module.css create mode 100644 apps/www/src/components/tokentable/tokentable.tsx diff --git a/apps/www/src/components/mdx/mdx-components.tsx b/apps/www/src/components/mdx/mdx-components.tsx index fb1766f40..0e0715366 100644 --- a/apps/www/src/components/mdx/mdx-components.tsx +++ b/apps/www/src/components/mdx/mdx-components.tsx @@ -11,6 +11,7 @@ import type { TableHTMLAttributes } from 'react'; import Demo from '../demo'; +import { TokenTable } from '../tokentable'; import { TypeTable } from '../typetable'; import { Code } from './code'; import styles from './mdx-components.module.css'; @@ -117,6 +118,9 @@ const mdxComponents = { className={cx(styles['prose-type-table'], props.className)} /> ), + TokenTable: (props: ComponentPropsWithoutRef) => ( + + ), Demo }; diff --git a/apps/www/src/components/tokentable/index.ts b/apps/www/src/components/tokentable/index.ts new file mode 100644 index 000000000..2e2a0cf53 --- /dev/null +++ b/apps/www/src/components/tokentable/index.ts @@ -0,0 +1,6 @@ +export { + type TokenItem, + TokenTable, + type TokenTableProps, + type TokenType +} from './tokentable'; diff --git a/apps/www/src/components/tokentable/tokentable.module.css b/apps/www/src/components/tokentable/tokentable.module.css new file mode 100644 index 000000000..5f6067f2f --- /dev/null +++ b/apps/www/src/components/tokentable/tokentable.module.css @@ -0,0 +1,255 @@ +.container { + display: flex; + flex-direction: column; + border: 0.5px solid var(--rs-color-border-base-primary); + border-radius: var(--rs-radius-2); + overflow: hidden; + margin: var(--rs-space-5) 0; +} + +.header { + display: flex; + align-items: center; + gap: var(--rs-space-4); + height: 36px; + padding: 0 var(--rs-space-4); + background: var(--rs-color-background-base-secondary); + border-bottom: 0.5px solid var(--rs-color-border-base-primary); + font-weight: var(--rs-font-weight-medium); + font-size: var(--rs-font-size-small); + line-height: var(--rs-line-height-small); + letter-spacing: var(--rs-letter-spacing-small); + color: var(--rs-color-foreground-base-primary); +} + +.previewLabel { + width: 40px; + flex-shrink: 0; +} + +.previewLabelWide { + width: 130px; + flex-shrink: 0; +} + +.tokenLabel { + width: 280px; + flex-shrink: 0; +} + +.tokenLabelWide { + width: 360px; + flex-shrink: 0; +} + +.valueLabel { + width: 120px; + flex-shrink: 0; +} + +.descriptionLabel { + flex: 1; +} + +.body { + display: flex; + flex-direction: column; +} + +.row { + display: flex; + align-items: center; + gap: var(--rs-space-4); + padding: var(--rs-space-3) var(--rs-space-4); + border-bottom: 0.5px solid var(--rs-color-border-base-primary); + transition: background-color 0.15s ease; +} + +.row:last-child { + border-bottom: none; +} + +.row:hover { + background: var(--rs-color-background-base-primary-hover); +} + +.previewCell { + width: 40px; + flex-shrink: 0; + display: flex; + align-items: center; + justify-content: center; +} + +.previewCellWide { + width: 130px; + flex-shrink: 0; + display: flex; + align-items: center; + justify-content: flex-start; +} + +.tokenCell { + width: 280px; + flex-shrink: 0; + display: flex; + align-items: center; +} + +.tokenCellWide { + width: 360px; + flex-shrink: 0; + display: flex; + align-items: center; +} + +.valueCell { + width: 120px; + flex-shrink: 0; +} + +.descriptionCell { + flex: 1; +} + +.tokenName { + font-family: var(--rs-font-mono); + font-size: var(--rs-font-size-mono-small); + line-height: var(--rs-line-height-mono-small); + color: var(--rs-color-foreground-base-primary); + background: transparent; + padding: 0; +} + +.tokenValue { + font-family: var(--rs-font-mono); + font-size: var(--rs-font-size-mono-small); + line-height: var(--rs-line-height-mono-small); + color: var(--rs-color-foreground-base-secondary); + background: transparent; + padding: 0; +} + +.description { + color: var(--rs-color-foreground-base-secondary); +} + +.copyButton { + display: inline-flex; + align-items: center; + justify-content: center; + width: 24px; + height: 24px; + padding: 0; + border: none; + background: transparent; + color: var(--rs-color-foreground-base-tertiary); + cursor: pointer; + border-radius: var(--rs-radius-2); + transition: all 0.15s ease; + opacity: 0; +} + +.row:hover .copyButton { + opacity: 1; +} + +.copyButton:hover { + background: var(--rs-color-background-neutral-secondary); + color: var(--rs-color-foreground-base-primary); +} + +.copyIconSuccess { + color: var(--rs-color-foreground-success-primary); +} + +/* Preview styles */ +.colorPreview { + width: 24px; + height: 24px; + border-radius: var(--rs-radius-2); + border: 1px solid var(--rs-color-border-base-secondary); + flex-shrink: 0; +} + +.spacingPreviewContainer { + width: 120px; + height: 24px; + display: flex; + align-items: center; + justify-content: flex-start; + background: var(--rs-color-background-neutral-secondary); + border-radius: var(--rs-radius-1); + overflow: hidden; +} + +.spacingPreview { + height: 100%; + min-width: 2px; + background: var(--rs-color-background-accent-emphasis); + border-radius: var(--rs-radius-1); +} + +.radiusPreview { + width: 24px; + height: 24px; + background: var(--rs-color-background-accent-emphasis); + flex-shrink: 0; +} + +.shadowPreview { + width: 20px; + height: 20px; + background: var(--rs-color-background-base-secondary); + border-radius: var(--rs-radius-2); + flex-shrink: 0; +} + +.blurPreviewContainer { + width: 24px; + height: 24px; + background: linear-gradient( + 135deg, + var(--rs-color-background-accent-emphasis) 0%, + var(--rs-color-background-danger-emphasis) 50%, + var(--rs-color-background-success-emphasis) 100% + ); + border-radius: var(--rs-radius-2); + position: relative; + overflow: hidden; +} + +.blurPreview { + position: absolute; + inset: 0; + background: var(--rs-color-overlay-white-a4); +} + +/* Responsive adjustments */ +@media (max-width: 768px) { + .header { + display: none; + } + + .row { + flex-direction: column; + align-items: flex-start; + gap: var(--rs-space-2); + padding: var(--rs-space-4); + } + + .previewCell, + .tokenCell, + .valueCell, + .descriptionCell { + width: 100%; + } + + .previewCell { + justify-content: flex-start; + } + + .copyButton { + opacity: 1; + } +} diff --git a/apps/www/src/components/tokentable/tokentable.tsx b/apps/www/src/components/tokentable/tokentable.tsx new file mode 100644 index 000000000..40219023c --- /dev/null +++ b/apps/www/src/components/tokentable/tokentable.tsx @@ -0,0 +1,174 @@ +'use client'; + +import { Flex, Text, Tooltip } from '@raystack/apsara'; +import { cx } from 'class-variance-authority'; +import { CheckIcon, CopyIcon } from 'lucide-react'; +import { type ReactNode, useCallback, useState } from 'react'; +import styles from './tokentable.module.css'; + +export type TokenType = + | 'color' + | 'spacing' + | 'radius' + | 'shadow' + | 'blur' + | 'typography' + | 'default'; + +export interface TokenItem { + /** The CSS variable name */ + name: string; + /** The token value (e.g., "4px", "#ffffff") - optional for semantic tokens */ + value?: string; + /** Description of the token's use case */ + description?: string; +} + +export interface TokenTableProps { + /** Array of token items to display */ + tokens: TokenItem[]; + /** Type of tokens for visual preview */ + type?: TokenType; + /** Additional CSS class name */ + className?: string; +} + +function CopyButton({ text }: { text: string }) { + const [copied, setCopied] = useState(false); + + const handleCopy = useCallback(async () => { + try { + await navigator.clipboard.writeText(text); + setCopied(true); + setTimeout(() => setCopied(false), 2000); + } catch (err) { + console.error('Failed to copy:', err); + } + }, [text]); + + return ( + + + + ); +} + +function TokenPreview({ token, type }: { token: TokenItem; type: TokenType }) { + switch (type) { + case 'color': + return ( +
+ ); + case 'spacing': + return ( +
+
+
+ ); + case 'radius': + return ( +
+ ); + case 'shadow': + return ( +
+ ); + case 'blur': + return ( +
+
+
+ ); + case 'typography': + return null; + default: + return null; + } +} + +export function TokenTable({ + tokens, + type = 'default', + className +}: TokenTableProps) { + const showPreview = type !== 'default' && type !== 'typography'; + const showValue = tokens.some(token => token.value); + const isSpacing = type === 'spacing'; + + return ( +
+
+ {showPreview && ( + + )} + + Token + + {showValue && Value} + Description +
+
+ {tokens.map(token => ( +
+ {showPreview && ( +
+ +
+ )} +
+ + {token.name} + + +
+ {showValue && ( +
+ {token.value} +
+ )} +
+ + {token.description} + +
+
+ ))} +
+
+ ); +} diff --git a/apps/www/src/content/docs/theme/colors/index.mdx b/apps/www/src/content/docs/theme/colors/index.mdx index 451f2f6c7..912bd6af1 100644 --- a/apps/www/src/content/docs/theme/colors/index.mdx +++ b/apps/www/src/content/docs/theme/colors/index.mdx @@ -3,8 +3,6 @@ title: Colors description: Overview of the color system and semantic color tokens in Apsara. --- -import { Table } from "@raystack/apsara"; - Apsara uses a semantic color system that provides meaningful, context-aware colors for your interface. Colors are organized by their purpose rather than their appearance, making it easy to maintain consistency and support theming. ## Foreground Colors @@ -13,93 +11,35 @@ Foreground colors are used for text, icons, and other content elements. ### Base Foreground - - - - Token - Description - - - - - --rs-color-foreground-base-primary - Primary text color for headings and important content - - - --rs-color-foreground-base-secondary - Secondary text color for supporting content - - - --rs-color-foreground-base-tertiary - Tertiary text color for muted or placeholder content - - - --rs-color-foreground-base-emphasis - High contrast text for emphasis on colored backgrounds - - -
+ ### Semantic Foreground - - - - Token - Description - - - - - --rs-color-foreground-accent-primary - Accent color for interactive elements and links - - - --rs-color-foreground-accent-primary-hover - Hover state for accent foreground - - - --rs-color-foreground-accent-emphasis - Text on accent emphasis backgrounds - - - --rs-color-foreground-danger-primary - Error and destructive action text - - - --rs-color-foreground-danger-primary-hover - Hover state for danger foreground - - - --rs-color-foreground-danger-emphasis - Text on danger emphasis backgrounds - - - --rs-color-foreground-attention-primary - Warning and attention text - - - --rs-color-foreground-attention-primary-hover - Hover state for attention foreground - - - --rs-color-foreground-attention-emphasis - Text on attention emphasis backgrounds - - - --rs-color-foreground-success-primary - Success and positive action text - - - --rs-color-foreground-success-primary-hover - Hover state for success foreground - - - --rs-color-foreground-success-emphasis - Text on success emphasis backgrounds - - -
+ ## Background Colors @@ -107,386 +47,127 @@ Background colors define surfaces and containers in your interface. ### Base Background - - - - Token - Description - - - - - --rs-color-background-base-primary - Primary background for main content areas - - - --rs-color-background-base-primary-hover - Hover state for primary background - - - --rs-color-background-base-secondary - Secondary background for cards and panels - - - --rs-color-background-neutral-primary - Neutral background for subtle elements - - - --rs-color-background-neutral-secondary - Secondary neutral background - - - --rs-color-background-neutral-secondary-hover - Hover state for secondary neutral background - - - --rs-color-background-neutral-tertiary - Tertiary neutral background - - - --rs-color-background-neutral-tertiary-hover - Hover state for tertiary neutral background - - - --rs-color-background-neutral-emphasis - High contrast neutral background - - -
+ ### Semantic Background - - - - Token - Description - - - - - --rs-color-background-accent-primary - Subtle accent background for highlights - - - --rs-color-background-accent-emphasis - Strong accent background for buttons and CTAs - - - --rs-color-background-accent-emphasis-hover - Hover state for accent emphasis background - - - --rs-color-background-danger-primary - Subtle danger background for error states - - - --rs-color-background-danger-emphasis - Strong danger background for destructive actions - - - --rs-color-background-danger-emphasis-hover - Hover state for danger emphasis background - - - --rs-color-background-attention-primary - Subtle attention background for warnings - - - --rs-color-background-attention-emphasis - Strong attention background - - - --rs-color-background-attention-emphasis-hover - Hover state for attention emphasis background - - - --rs-color-background-success-primary - Subtle success background for positive states - - - --rs-color-background-success-emphasis - Strong success background - - - --rs-color-background-success-emphasis-hover - Hover state for success emphasis background - - -
+ ## Border Colors Border colors define boundaries and separators. - - - - Token - Description - - - - - --rs-color-border-base-primary - Primary border for subtle boundaries - - - --rs-color-border-base-secondary - Secondary border for dividers - - - --rs-color-border-base-tertiary - Tertiary border for inputs and cards - - - --rs-color-border-base-tertiary-hover - Hover state for tertiary border - - - --rs-color-border-base-focus - Focus ring for interactive elements - - - --rs-color-border-base-emphasis - High contrast border for emphasis - - - --rs-color-border-accent-primary - Accent border for highlights - - - --rs-color-border-accent-emphasis - Strong accent border - - - --rs-color-border-accent-emphasis-hover - Hover state for accent emphasis border - - - --rs-color-border-danger-primary - Danger border for error states - - - --rs-color-border-danger-emphasis - Strong danger border - - - --rs-color-border-danger-emphasis-hover - Hover state for danger emphasis border - - - --rs-color-border-attention-primary - Attention border for warnings - - - --rs-color-border-attention-emphasis - Strong attention border - - - --rs-color-border-attention-emphasis-hover - Hover state for attention emphasis border - - - --rs-color-border-success-primary - Success border for positive states - - - --rs-color-border-success-emphasis - Strong success border - - - --rs-color-border-success-emphasis-hover - Hover state for success emphasis border - - -
+ ## Overlay Colors Overlay colors are used for modals, tooltips, and layered elements. - - - - Token - Opacity - - - - - --rs-color-overlay-base-primary - Default overlay - - - --rs-color-overlay-black-a1 - 5% - - - --rs-color-overlay-black-a2 - 10% - - - --rs-color-overlay-black-a3 - 15% - - - --rs-color-overlay-black-a4 - 20% - - - --rs-color-overlay-black-a5 - 30% - - - --rs-color-overlay-black-a6 - 40% - - - --rs-color-overlay-black-a7 - 50% - - - --rs-color-overlay-black-a8 - 60% - - - --rs-color-overlay-black-a9 - 70% - - - --rs-color-overlay-black-a10 - 80% - - - --rs-color-overlay-black-a11 - 90% - - - --rs-color-overlay-black-a12 - 95% - - - --rs-color-overlay-white-a1 - 5% - - - --rs-color-overlay-white-a2 - 10% - - - --rs-color-overlay-white-a3 - 15% - - - --rs-color-overlay-white-a4 - 20% - - - --rs-color-overlay-white-a5 - 30% - - - --rs-color-overlay-white-a6 - 40% - - - --rs-color-overlay-white-a7 - 50% - - - --rs-color-overlay-white-a8 - 60% - - - --rs-color-overlay-white-a9 - 70% - - - --rs-color-overlay-white-a10 - 80% - - - --rs-color-overlay-white-a11 - 90% - - - --rs-color-overlay-white-a12 - 95% - - -
+ ## Visualization Colors A palette of colors designed for data visualization, charts, and graphs. - - - - Color - Tokens - - - - - Sky - --rs-color-viz-sky-6, --rs-color-viz-sky-8, --rs-color-viz-sky-9, --rs-color-viz-sky-11 - - - Mint - --rs-color-viz-mint-6, --rs-color-viz-mint-8, --rs-color-viz-mint-9, --rs-color-viz-mint-11 - - - Lime - --rs-color-viz-lime-6, --rs-color-viz-lime-8, --rs-color-viz-lime-9, --rs-color-viz-lime-11 - - - Grass - --rs-color-viz-grass-6, --rs-color-viz-grass-8, --rs-color-viz-grass-9, --rs-color-viz-grass-11 - - - Green - --rs-color-viz-green-6, --rs-color-viz-green-8, --rs-color-viz-green-9, --rs-color-viz-green-11 - - - Jade - --rs-color-viz-jade-6, --rs-color-viz-jade-8, --rs-color-viz-jade-9, --rs-color-viz-jade-11 - - - Cyan - --rs-color-viz-cyan-6, --rs-color-viz-cyan-8, --rs-color-viz-cyan-9, --rs-color-viz-cyan-11 - - - Blue - --rs-color-viz-blue-6, --rs-color-viz-blue-8, --rs-color-viz-blue-9, --rs-color-viz-blue-11 - - - Iris - --rs-color-viz-iris-6, --rs-color-viz-iris-8, --rs-color-viz-iris-9, --rs-color-viz-iris-11 - - - Purple - --rs-color-viz-purple-6, --rs-color-viz-purple-8, --rs-color-viz-purple-9, --rs-color-viz-purple-11 - - - Pink - --rs-color-viz-pink-6, --rs-color-viz-pink-8, --rs-color-viz-pink-9, --rs-color-viz-pink-11 - - - Crimson - --rs-color-viz-crimson-6, --rs-color-viz-crimson-8, --rs-color-viz-crimson-9, --rs-color-viz-crimson-11 - - - Orange - --rs-color-viz-orange-6, --rs-color-viz-orange-8, --rs-color-viz-orange-9, --rs-color-viz-orange-11 - - - Gold - --rs-color-viz-gold-6, --rs-color-viz-gold-8, --rs-color-viz-gold-9, --rs-color-viz-gold-11 - - -
+ ## Usage diff --git a/apps/www/src/content/docs/theme/effects/index.mdx b/apps/www/src/content/docs/theme/effects/index.mdx index b0814048e..956537756 100644 --- a/apps/www/src/content/docs/theme/effects/index.mdx +++ b/apps/www/src/content/docs/theme/effects/index.mdx @@ -3,86 +3,36 @@ title: Effects description: Overview of shadow and blur effect tokens in Apsara. --- -import { Table } from "@raystack/apsara"; - Effects add depth and visual hierarchy to your interface through shadows and blur. Apsara provides semantic effect tokens that work consistently across light and dark themes. ## Shadows Shadow tokens create elevation and depth, helping users understand the layering of interface elements. - - - - Token - Description - Use Case - - - - - --rs-shadow-feather - Subtle, minimal shadow - Cards, subtle elevation - - - --rs-shadow-soft - Soft, gentle shadow - Buttons, interactive elements - - - --rs-shadow-lifted - Noticeable elevation - Dropdowns, popovers - - - --rs-shadow-floating - Strong floating effect - Modals, dialogs, tooltips - - - --rs-shadow-inset - Inner shadow - Pressed states, inputs - - -
+ ## Blur Effects Blur tokens are used for backdrop effects and creating depth through transparency. - - - - Token - Value - Use Case - - - - - --rs-blur-sm - blur(0.5px) - Subtle blur effect - - - --rs-blur-md - blur(1px) - Medium blur effect - - - --rs-blur-lg - blur(2px) - Noticeable blur effect - - - --rs-blur-xl - blur(4px) - Strong blur for overlays - - -
+ ## Usage @@ -134,42 +84,16 @@ Blur tokens are used for backdrop effects and creating depth through transparenc Use shadows to establish visual hierarchy and indicate interactive states: - - - - Level - Shadow - Examples - - - - - Level 0 - None - Flat surfaces, backgrounds - - - Level 1 - --rs-shadow-feather - Cards, panels - - - Level 2 - --rs-shadow-soft - Buttons, interactive cards - - - Level 3 - --rs-shadow-lifted - Dropdowns, popovers, hover states - - - Level 4 - --rs-shadow-floating - Modals, dialogs, toasts - - -
+ ## Best Practices diff --git a/apps/www/src/content/docs/theme/overview/index.mdx b/apps/www/src/content/docs/theme/overview/index.mdx index e632d7acd..2b03dc36a 100644 --- a/apps/www/src/content/docs/theme/overview/index.mdx +++ b/apps/www/src/content/docs/theme/overview/index.mdx @@ -3,8 +3,6 @@ title: Overview description: Understanding the Apsara theming system and ThemeProvider. --- -import { Table } from "@raystack/apsara"; - Apsara provides a flexible theming system that supports light and dark modes, multiple accent colors, gray color variants, and style presets. The `ThemeProvider` component manages theme state and applies the appropriate CSS variables to your application. ## Installation @@ -27,105 +25,48 @@ function App() { Apsara supports three theme modes: - - - - Mode - Description - - - - - light - Light color scheme - - - dark - Dark color scheme - - - system - Follows the user's system preference - - -
+ ## Style Variants Style variants affect the overall visual appearance, including border radius and typography: - - - - Style - Description - - - - - modern - Sharp corners, Inter font family (default) - - - traditional - Softer, rounded corners, Lora/Josefin Sans fonts - - -
+ ## Accent Colors Accent colors define the primary brand color used throughout the interface: - - - - Color - Description - - - - - indigo - Blue-violet accent (default) - - - orange - Warm orange accent - - - mint - Fresh mint/teal accent - - -
+ ## Gray Colors Gray color variants affect neutral tones throughout the interface: - - - - Color - Description - - - - - gray - Pure neutral gray (default) - - - mauve - Warm gray with purple undertone - - - slate - Cool gray with blue undertone - - -
+ ## ThemeProvider Props @@ -213,37 +154,14 @@ function App() { The ThemeProvider sets the following attributes on the document element: - - - - Attribute - Example Value - Description - - - - - data-theme - "light" or "dark" - Current color scheme - - - data-style - "modern" or "traditional" - Visual style variant - - - data-accent-color - "indigo" - Accent color - - - data-gray-color - "gray" - Gray color variant - - -
+ ## Avoiding Flash diff --git a/apps/www/src/content/docs/theme/radius/index.mdx b/apps/www/src/content/docs/theme/radius/index.mdx index 5df2ef3be..324c11f39 100644 --- a/apps/www/src/content/docs/theme/radius/index.mdx +++ b/apps/www/src/content/docs/theme/radius/index.mdx @@ -3,8 +3,6 @@ title: Radius description: Overview of the border radius scale and style variants in Apsara. --- -import { Table } from "@raystack/apsara"; - Border radius tokens control the roundness of corners throughout your interface. Apsara provides a consistent radius scale with support for different style variants. ## Radius Scale @@ -13,152 +11,49 @@ The radius scale provides 7 tokens for different levels of roundness, from subtl ### Modern Style (Default) - - - - Token - Value - Use Case - - - - - --rs-radius-1 - 2px - Subtle rounding for small elements - - - --rs-radius-2 - 4px - Badges, chips, small buttons - - - --rs-radius-3 - 6px - Inputs, buttons, cards - - - --rs-radius-4 - 8px - Modals, dialogs, larger cards - - - --rs-radius-5 - 12px - Large containers, panels - - - --rs-radius-6 - 16px - Extra large containers - - - --rs-radius-full - 800px - Pills, circular elements, avatars - - -
+ ### Traditional Style When using `data-style="traditional"`, the radius values increase for a softer, more rounded appearance. - - - - Token - Value - Use Case - - - - - --rs-radius-1 - 8px - Subtle rounding for small elements - - - --rs-radius-2 - 16px - Badges, chips, small buttons - - - --rs-radius-3 - 20px - Inputs, buttons, cards - - - --rs-radius-4 - 24px - Modals, dialogs, larger cards - - - --rs-radius-5 - 32px - Large containers, panels - - - --rs-radius-6 - 40px - Extra large containers - - - --rs-radius-full - 1600px - Pills, circular elements, avatars - - -
+ ## Style Comparison - - - - Token - Modern - Traditional - - - - - --rs-radius-1 - 2px - 8px - - - --rs-radius-2 - 4px - 16px - - - --rs-radius-3 - 6px - 20px - - - --rs-radius-4 - 8px - 24px - - - --rs-radius-5 - 12px - 32px - - - --rs-radius-6 - 16px - 40px - - - --rs-radius-full - 800px - 1600px - - -
+ ## Usage diff --git a/apps/www/src/content/docs/theme/spacing/index.mdx b/apps/www/src/content/docs/theme/spacing/index.mdx index 78aa1c954..a05e6dad9 100644 --- a/apps/www/src/content/docs/theme/spacing/index.mdx +++ b/apps/www/src/content/docs/theme/spacing/index.mdx @@ -3,110 +3,34 @@ title: Spacing description: Overview of the space scale and spacing tokens in Apsara. --- -import { Table } from "@raystack/apsara"; - Consistent spacing creates visual rhythm and hierarchy in your interface. Apsara provides a comprehensive spacing scale through CSS custom properties that you can use throughout your application. ## Scale Spacing values are derived from a 17-step scale, which provides fine-grained control over layout spacing. The scale starts at 2px and progressively increases to 120px, allowing for both tight and spacious layouts. - - - - Token - Value - Use Case - - - - - --rs-space-1 - 2px - Minimal spacing, icon gaps - - - --rs-space-2 - 4px - Tight spacing, small gaps - - - --rs-space-3 - 8px - Compact padding, inline spacing - - - --rs-space-4 - 12px - Standard small padding - - - --rs-space-5 - 16px - Default padding, common gaps - - - --rs-space-6 - 20px - Medium padding - - - --rs-space-7 - 24px - Comfortable spacing - - - --rs-space-8 - 28px - Generous padding - - - --rs-space-9 - 32px - Large spacing - - - --rs-space-10 - 40px - Section gaps - - - --rs-space-11 - 48px - Large section spacing - - - --rs-space-12 - 56px - Extra large spacing - - - --rs-space-13 - 64px - Major divisions - - - --rs-space-14 - 72px - Layout spacing - - - --rs-space-15 - 80px - Page sections - - - --rs-space-16 - 96px - Large page sections - - - --rs-space-17 - 120px - Maximum spacing - - -
+ ## Tokens @@ -137,42 +61,14 @@ var(--rs-space-17); /* 120px */ The spacing scale can be organized into semantic groups for easier selection: - - - - Group - Tokens - Values - Purpose - - - - - Compact - 1-3 - 2px - 8px - Tight UI elements, icon spacing - - - Comfortable - 4-7 - 12px - 24px - Standard component padding - - - Spacious - 8-11 - 28px - 48px - Section spacing, larger gaps - - - Layout - 12-17 - 56px - 120px - Page sections, major divisions - - -
+ ## Best Practices diff --git a/apps/www/src/content/docs/theme/typography/index.mdx b/apps/www/src/content/docs/theme/typography/index.mdx index a235b9698..dc4cd4506 100644 --- a/apps/www/src/content/docs/theme/typography/index.mdx +++ b/apps/www/src/content/docs/theme/typography/index.mdx @@ -3,97 +3,43 @@ title: Typography description: Overview of the typography system and text tokens in Apsara. --- -import { Table } from "@raystack/apsara"; - Apsara provides a comprehensive typography system with carefully crafted font families, sizes, weights, and spacing to ensure readable and consistent text across your application. ## Font Families Apsara includes three font family categories for different use cases. - - - - Token - Default Value - Use Case - - - - - --rs-font-title - Inter, sans-serif - Headings and titles - - - --rs-font-body - Inter, sans-serif - Body text and paragraphs - - - --rs-font-mono - Menlo, JetBrains Mono, monospace - Code and technical content - - -
+ ### Available Fonts - - - - Token - Font - - - - - --rs-font-inter - Inter - - - --rs-font-lora - Lora - - - --rs-font-josefin-sans - Josefin Sans - - - --rs-font-jetbrains-mono - JetBrains Mono - - - --rs-font-menlo - Menlo - - -
+ ## Font Weights - - - - Token - Value - Use Case - - - - - --rs-font-weight-regular - 400 - Body text, descriptions - - - --rs-font-weight-medium - 500 - Headings, labels, emphasis - - -
+ ## Body Text @@ -101,108 +47,42 @@ Font sizes, line heights, and letter spacing for body content. ### Font Sizes - - - - Token - Size - Use Case - - - - - --rs-font-size-micro - 10px - Fine print, timestamps - - - --rs-font-size-mini - 11px - Captions, badges - - - --rs-font-size-small - 12px - Secondary text, labels - - - --rs-font-size-regular - 14px - Default body text - - - --rs-font-size-large - 16px - Large body text, introductions - - -
+ ### Line Heights - - - - Token - Value - - - - - --rs-line-height-micro - 12px - - - --rs-line-height-mini - 16px - - - --rs-line-height-small - 16px - - - --rs-line-height-regular - 20px - - - --rs-line-height-large - 24px - - -
+ ### Letter Spacing - - - - Token - Value - - - - - --rs-letter-spacing-micro - 0.5px - - - --rs-letter-spacing-mini - 0.5px - - - --rs-letter-spacing-small - 0.4px - - - --rs-letter-spacing-regular - 0.25px - - - --rs-letter-spacing-large - 0.5px - - -
+ ## Title Text @@ -210,95 +90,39 @@ Font sizes, line heights, and letter spacing for headings and titles. ### Font Sizes - - - - Token - Size - Use Case - - - - - --rs-font-size-t1 - 20px - Small headings (h4) - - - --rs-font-size-t2 - 24px - Section headings (h3) - - - --rs-font-size-t3 - 28px - Page headings (h2) - - - --rs-font-size-t4 - 32px - Main titles (h1) - - -
+ ### Line Heights - - - - Token - Value - - - - - --rs-line-height-t1 - 24px - - - --rs-line-height-t2 - 32px - - - --rs-line-height-t3 - 36px - - - --rs-line-height-t4 - 40px - - -
+ ### Letter Spacing - - - - Token - Value - - - - - --rs-letter-spacing-t1 - 0 - - - --rs-letter-spacing-t2 - 0 - - - --rs-letter-spacing-t3 - 0 - - - --rs-letter-spacing-t4 - 0 - - -
+ ## Monospace Text @@ -306,90 +130,39 @@ Font sizes, line heights, and letter spacing for code and technical content. ### Font Sizes - - - - Token - Size - - - - - --rs-font-size-mono-mini - 11px - - - --rs-font-size-mono-small - 12px - - - --rs-font-size-mono-regular - 14px - - - --rs-font-size-mono-large - 16px - - -
+ ### Line Heights - - - - Token - Value - - - - - --rs-line-height-mono-mini - 16px - - - --rs-line-height-mono-small - 16px - - - --rs-line-height-mono-regular - 20px - - - --rs-line-height-mono-large - 24px - - -
+ ### Letter Spacing - - - - Token - Value - - - - - --rs-letter-spacing-mono-mini - 0px - - - --rs-letter-spacing-mono-small - 0px - - - --rs-letter-spacing-mono-regular - 0px - - - --rs-letter-spacing-mono-large - 0px - - -
+ ## Style Variants @@ -399,24 +172,13 @@ Apsara supports different style variants that change typography to match your de When using `data-style="traditional"`, the font families change to: - - - - Token - Traditional Value - - - - - --rs-font-title - Lora, serif - - - --rs-font-body - Josefin Sans, sans-serif - - -
+ ## Usage From d812a8b52f5c75a5a0196258c7a33fb7cdb579e7 Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Sun, 1 Feb 2026 16:16:44 -0600 Subject: [PATCH 3/8] docs: improve theme documentation structure and content - Consolidate typography tables (body, title, mono) for better readability - Remove redundant Style Comparison and Elevation Hierarchy sections - Add Token Naming Convention section to overview - Improve intro descriptions explaining semantic token behavior - Add Usage section to spacing with practical examples - Update all Usage sections with real-world patterns (dashboards, data tables, command palettes, etc.) instead of basic component styling --- .../src/content/docs/theme/colors/index.mdx | 94 +++++----- .../src/content/docs/theme/effects/index.mdx | 81 +++++---- .../src/content/docs/theme/overview/index.mdx | 30 ++++ .../src/content/docs/theme/radius/index.mdx | 80 +++++---- .../src/content/docs/theme/spacing/index.mdx | 70 +++++--- .../content/docs/theme/typography/index.mdx | 166 ++++++++---------- 6 files changed, 289 insertions(+), 232 deletions(-) diff --git a/apps/www/src/content/docs/theme/colors/index.mdx b/apps/www/src/content/docs/theme/colors/index.mdx index 912bd6af1..88ebbbd0b 100644 --- a/apps/www/src/content/docs/theme/colors/index.mdx +++ b/apps/www/src/content/docs/theme/colors/index.mdx @@ -3,14 +3,12 @@ title: Colors description: Overview of the color system and semantic color tokens in Apsara. --- -Apsara uses a semantic color system that provides meaningful, context-aware colors for your interface. Colors are organized by their purpose rather than their appearance, making it easy to maintain consistency and support theming. +Apsara uses a semantic color system that provides meaningful, context-aware colors for your interface. Rather than using fixed color values, semantic tokens represent the intended purpose of a color—such as "primary text" or "danger background"—and automatically resolve to the appropriate value based on the active theme and style. This abstraction allows you to build consistent, themeable interfaces by focusing on what a color represents rather than what it looks like. ## Foreground Colors Foreground colors are used for text, icons, and other content elements. -### Base Foreground - - -### Semantic Foreground - - - -### Semantic Background - - +/* Draggable item while dragging */ +.draggable[data-dragging="true"] { + box-shadow: var(--rs-shadow-floating); +} +``` ## Best Practices diff --git a/apps/www/src/content/docs/theme/overview/index.mdx b/apps/www/src/content/docs/theme/overview/index.mdx index 2b03dc36a..f8bf8f243 100644 --- a/apps/www/src/content/docs/theme/overview/index.mdx +++ b/apps/www/src/content/docs/theme/overview/index.mdx @@ -68,6 +68,36 @@ Gray color variants affect neutral tones throughout the interface: ]} /> +## Token Naming Convention + +Apsara tokens follow a consistent naming pattern that makes them easy to discover and use: + +``` +--rs-{category}-{property}-{variant}-{state} +``` + + + +### Examples + + + ## ThemeProvider Props diff --git a/apps/www/src/content/docs/theme/radius/index.mdx b/apps/www/src/content/docs/theme/radius/index.mdx index 324c11f39..57d1eaba5 100644 --- a/apps/www/src/content/docs/theme/radius/index.mdx +++ b/apps/www/src/content/docs/theme/radius/index.mdx @@ -3,7 +3,7 @@ title: Radius description: Overview of the border radius scale and style variants in Apsara. --- -Border radius tokens control the roundness of corners throughout your interface. Apsara provides a consistent radius scale with support for different style variants. +Border radius tokens control the roundness of corners throughout your interface. These tokens automatically adjust based on the active style variant—modern style uses sharp, minimal radii while traditional style uses softer, more rounded corners. By using radius tokens instead of fixed values, your custom components will seamlessly adapt when the style changes. ## Radius Scale @@ -41,56 +41,72 @@ When using `data-style="traditional"`, the radius values increase for a softer, ]} /> -## Style Comparison - - - ## Usage ```css -/* Buttons */ -.button { - border-radius: var(--rs-radius-3); +/* Dashboard widget container */ +.widget { + border-radius: var(--rs-radius-4); + overflow: hidden; +} + +.widget-header { + border-radius: var(--rs-radius-4) var(--rs-radius-4) 0 0; +} + +/* Filter tags with remove button */ +.filter-tag { + border-radius: var(--rs-radius-full); + display: inline-flex; + align-items: center; + gap: var(--rs-space-2); } -/* Cards */ -.card { +/* Nested card with image */ +.preview-card { border-radius: var(--rs-radius-4); } -/* Badges and chips */ -.badge { - border-radius: var(--rs-radius-2); +.preview-card-image { + border-radius: var(--rs-radius-3); +} + +/* Search results dropdown */ +.search-results { + border-radius: var(--rs-radius-3); +} + +.search-result-item:first-child { + border-radius: var(--rs-radius-3) var(--rs-radius-3) 0 0; +} + +.search-result-item:last-child { + border-radius: 0 0 var(--rs-radius-3) var(--rs-radius-3); } -/* Pills and tags */ -.pill { +/* User avatar with status indicator */ +.avatar-wrapper { + position: relative; +} + +.avatar-image { border-radius: var(--rs-radius-full); } -/* Avatar */ -.avatar { +.avatar-status { border-radius: var(--rs-radius-full); + position: absolute; + bottom: 0; + right: 0; } -/* Input fields */ -.input { +/* Segmented control */ +.segmented-control { border-radius: var(--rs-radius-3); } -/* Modal */ -.modal { - border-radius: var(--rs-radius-5); +.segmented-control-item[data-active="true"] { + border-radius: var(--rs-radius-2); } ``` diff --git a/apps/www/src/content/docs/theme/spacing/index.mdx b/apps/www/src/content/docs/theme/spacing/index.mdx index a05e6dad9..589c3e2f0 100644 --- a/apps/www/src/content/docs/theme/spacing/index.mdx +++ b/apps/www/src/content/docs/theme/spacing/index.mdx @@ -3,7 +3,7 @@ title: Spacing description: Overview of the space scale and spacing tokens in Apsara. --- -Consistent spacing creates visual rhythm and hierarchy in your interface. Apsara provides a comprehensive spacing scale through CSS custom properties that you can use throughout your application. +Consistent spacing creates visual rhythm and hierarchy in your interface. Apsara provides a comprehensive spacing scale through CSS custom properties that maintain proportional relationships across your application. These tokens ensure consistent spacing whether you're building custom layouts, extending components, or creating new UI patterns. ## Scale @@ -32,31 +32,6 @@ Spacing values are derived from a 17-step scale, which provides fine-grained con ]} /> -## Tokens - -Space scale tokens can be accessed using CSS variables. Use these tokens to style your custom components, ensuring they are consistent with the rest of your theme. - -```css -/* Space scale */ -var(--rs-space-1); /* 2px */ -var(--rs-space-2); /* 4px */ -var(--rs-space-3); /* 8px */ -var(--rs-space-4); /* 12px */ -var(--rs-space-5); /* 16px */ -var(--rs-space-6); /* 20px */ -var(--rs-space-7); /* 24px */ -var(--rs-space-8); /* 28px */ -var(--rs-space-9); /* 32px */ -var(--rs-space-10); /* 40px */ -var(--rs-space-11); /* 48px */ -var(--rs-space-12); /* 56px */ -var(--rs-space-13); /* 64px */ -var(--rs-space-14); /* 72px */ -var(--rs-space-15); /* 80px */ -var(--rs-space-16); /* 96px */ -var(--rs-space-17); /* 120px */ -``` - ## Semantic Groupings The spacing scale can be organized into semantic groups for easier selection: @@ -70,6 +45,49 @@ The spacing scale can be organized into semantic groups for easier selection: ]} /> +## Usage + +```css +/* Custom card grid layout */ +.card-grid { + display: grid; + gap: var(--rs-space-5); + padding: var(--rs-space-7); +} + +/* Sidebar navigation */ +.sidebar-nav { + display: flex; + flex-direction: column; + gap: var(--rs-space-2); + padding: var(--rs-space-4) var(--rs-space-5); +} + +/* Page section with header */ +.page-section { + margin-top: var(--rs-space-13); +} + +.page-section-header { + margin-bottom: var(--rs-space-6); +} + +/* Form field groups */ +.form-group { + display: flex; + flex-direction: column; + gap: var(--rs-space-3); + margin-bottom: var(--rs-space-5); +} + +/* Inline icon with text */ +.icon-text { + display: flex; + align-items: center; + gap: var(--rs-space-2); +} +``` + ## Best Practices - **Use smaller values (1-5)** for internal component spacing like padding and gaps between inline elements diff --git a/apps/www/src/content/docs/theme/typography/index.mdx b/apps/www/src/content/docs/theme/typography/index.mdx index dc4cd4506..f6b680b4d 100644 --- a/apps/www/src/content/docs/theme/typography/index.mdx +++ b/apps/www/src/content/docs/theme/typography/index.mdx @@ -3,7 +3,7 @@ title: Typography description: Overview of the typography system and text tokens in Apsara. --- -Apsara provides a comprehensive typography system with carefully crafted font families, sizes, weights, and spacing to ensure readable and consistent text across your application. +Apsara provides a comprehensive typography system with carefully crafted font families, sizes, weights, and spacing. Typography tokens adapt based on the active style variant—modern style uses Inter for a clean, technical aesthetic while traditional style uses Lora and Josefin Sans for a warmer, editorial feel. Using these tokens ensures your text styling remains consistent and automatically adapts to style changes. ## Font Families @@ -45,42 +45,24 @@ Apsara includes three font family categories for different use cases. Font sizes, line heights, and letter spacing for body content. -### Font Sizes - - -### Line Heights - - - -### Letter Spacing - - @@ -88,39 +70,21 @@ Font sizes, line heights, and letter spacing for body content. Font sizes, line heights, and letter spacing for headings and titles. -### Font Sizes - - -### Line Heights - - - -### Letter Spacing - - @@ -128,39 +92,21 @@ Font sizes, line heights, and letter spacing for headings and titles. Font sizes, line heights, and letter spacing for code and technical content. -### Font Sizes - - -### Line Heights - - - -### Letter Spacing - - @@ -183,36 +129,68 @@ When using `data-style="traditional"`, the font families change to: ## Usage ```css -/* Body text */ -.paragraph { +/* Dashboard metric display */ +.metric-label { font-family: var(--rs-font-body); - font-size: var(--rs-font-size-regular); + font-size: var(--rs-font-size-small); font-weight: var(--rs-font-weight-regular); - line-height: var(--rs-line-height-regular); - letter-spacing: var(--rs-letter-spacing-regular); + line-height: var(--rs-line-height-small); + letter-spacing: var(--rs-letter-spacing-small); + text-transform: uppercase; +} + +.metric-value { + font-family: var(--rs-font-title); + font-size: var(--rs-font-size-t3); + font-weight: var(--rs-font-weight-medium); + line-height: var(--rs-line-height-t3); } -/* Headings */ -.heading { +/* Article or blog post layout */ +.article-title { font-family: var(--rs-font-title); - font-size: var(--rs-font-size-t2); + font-size: var(--rs-font-size-t4); + line-height: var(--rs-line-height-t4); font-weight: var(--rs-font-weight-medium); - line-height: var(--rs-line-height-t2); } -/* Code */ -.code { +.article-meta { + font-size: var(--rs-font-size-mini); + line-height: var(--rs-line-height-mini); + letter-spacing: var(--rs-letter-spacing-mini); +} + +.article-body { + font-family: var(--rs-font-body); + font-size: var(--rs-font-size-regular); + line-height: var(--rs-line-height-regular); +} + +/* Terminal or log output */ +.log-output { font-family: var(--rs-font-mono); font-size: var(--rs-font-size-mono-small); line-height: var(--rs-line-height-mono-small); } -/* Small text */ -.caption { +.log-timestamp { + font-family: var(--rs-font-mono); + font-size: var(--rs-font-size-mono-mini); + line-height: var(--rs-line-height-mono-mini); +} + +/* Data table headers and cells */ +.table-header { font-size: var(--rs-font-size-small); + font-weight: var(--rs-font-weight-medium); line-height: var(--rs-line-height-small); letter-spacing: var(--rs-letter-spacing-small); } + +.table-cell { + font-size: var(--rs-font-size-regular); + line-height: var(--rs-line-height-regular); +} ``` ## Best Practices From c198b94529924f5a0ec63c6b4bbe7399a56ff581 Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Sun, 1 Feb 2026 21:03:08 -0600 Subject: [PATCH 4/8] docs: redesign theme overview page and style markdown tables - Restructure overview with cleaner hierarchy (5 focused sections) - Replace verbose bullet lists with concise formats - Add use-case focused customization examples - Improve API Reference with better explanations for ThemeProvider and useTheme - Add markdown table styles matching TokenTable appearance - Add CSS usage example showing how to use tokens - Link token categories to their respective documentation pages --- .../components/mdx/mdx-components.module.css | 49 +++++ .../www/src/components/mdx/mdx-components.tsx | 7 +- .../src/content/docs/theme/overview/index.mdx | 206 +++++------------- 3 files changed, 112 insertions(+), 150 deletions(-) diff --git a/apps/www/src/components/mdx/mdx-components.module.css b/apps/www/src/components/mdx/mdx-components.module.css index fcf076049..484c419f4 100644 --- a/apps/www/src/components/mdx/mdx-components.module.css +++ b/apps/www/src/components/mdx/mdx-components.module.css @@ -58,3 +58,52 @@ :global(.prose) ol:not([data-demo] ol) li:first-child { margin-top: var(--rs-space-3); } + +/* Markdown table styles */ +.prose-table { + width: 100%; + border: 0.5px solid var(--rs-color-border-base-primary); + border-radius: var(--rs-radius-2); + overflow: hidden; + margin: var(--rs-space-5) 0; + border-collapse: separate; + border-spacing: 0; +} + +.prose-table thead { + background: var(--rs-color-background-base-secondary); +} + +.prose-table th { + text-align: left; + padding: var(--rs-space-3) var(--rs-space-4); + font-weight: var(--rs-font-weight-medium); + font-size: var(--rs-font-size-small); + line-height: var(--rs-line-height-small); + letter-spacing: var(--rs-letter-spacing-small); + color: var(--rs-color-foreground-base-primary); + border-bottom: 0.5px solid var(--rs-color-border-base-primary); +} + +.prose-table td { + padding: var(--rs-space-3) var(--rs-space-4); + font-size: var(--rs-font-size-small); + line-height: var(--rs-line-height-small); + color: var(--rs-color-foreground-base-secondary); + border-bottom: 0.5px solid var(--rs-color-border-base-primary); +} + +.prose-table tbody tr:last-child td { + border-bottom: none; +} + +.prose-table tbody tr:hover { + background: var(--rs-color-background-base-primary-hover); +} + +.prose-table code { + font-family: var(--rs-font-mono); + font-size: var(--rs-font-size-mono-small); + line-height: var(--rs-line-height-mono-small); + color: var(--rs-color-foreground-base-primary); +} diff --git a/apps/www/src/components/mdx/mdx-components.tsx b/apps/www/src/components/mdx/mdx-components.tsx index 0e0715366..8c1b35014 100644 --- a/apps/www/src/components/mdx/mdx-components.tsx +++ b/apps/www/src/components/mdx/mdx-components.tsx @@ -34,8 +34,11 @@ function Image( function Table(props: TableHTMLAttributes) { return ( -
- +
+
); } diff --git a/apps/www/src/content/docs/theme/overview/index.mdx b/apps/www/src/content/docs/theme/overview/index.mdx index f8bf8f243..48ea739f5 100644 --- a/apps/www/src/content/docs/theme/overview/index.mdx +++ b/apps/www/src/content/docs/theme/overview/index.mdx @@ -3,7 +3,7 @@ title: Overview description: Understanding the Apsara theming system and ThemeProvider. --- -Apsara provides a flexible theming system that supports light and dark modes, multiple accent colors, gray color variants, and style presets. The `ThemeProvider` component manages theme state and applies the appropriate CSS variables to your application. +Apsara provides a theming system built on CSS custom properties (tokens). Tokens are semantic variables that automatically resolve to appropriate values based on the active theme—so your UI adapts seamlessly when users switch between light and dark modes or when you change accent colors, without any code changes. ## Installation @@ -14,103 +14,81 @@ import { ThemeProvider } from "@raystack/apsara"; function App() { return ( - - {/* Your application */} + + ); } ``` -## Theme Modes - -Apsara supports three theme modes: +## Customization - +The ThemeProvider accepts props to control the visual identity of your application. Combine `style` variants with `accentColor` and `grayColor` to create distinct aesthetics—from sharp and technical to warm and editorial. The `defaultTheme` prop controls light/dark mode, with `system` respecting the user's OS preference. -## Style Variants - -Style variants affect the overall visual appearance, including border radius and typography: +```tsx +// Clean, technical aesthetic + - +// Warm, editorial feel + -## Accent Colors +// Vibrant and fresh + +``` -Accent colors define the primary brand color used throughout the interface: +See [API Reference](#api-reference) for all available props and options. - +## Tokens -## Gray Colors +Tokens follow a consistent naming pattern: -Gray color variants affect neutral tones throughout the interface: +``` +--rs-{category}-{property}-{variant}-{state} +``` - +**Examples:** +- `--rs-color-foreground-base-primary` — primary text color +- `--rs-color-background-accent-emphasis` — accent button background +- `--rs-space-5` — 16px spacing +- `--rs-radius-3` — medium border radius +- `--rs-shadow-lifted` — elevated shadow + +**Using tokens in CSS:** + +```css +.custom-card { + background: var(--rs-color-background-base-secondary); + border: 1px solid var(--rs-color-border-base-primary); + border-radius: var(--rs-radius-4); + padding: var(--rs-space-5); + box-shadow: var(--rs-shadow-feather); +} +``` -## Token Naming Convention +**Token Categories:** +- [Colors](/theme/colors) — foreground, background, border, and overlay colors +- [Spacing](/theme/spacing) — consistent scale from 2px to 120px +- [Radius](/theme/radius) — border radius that adapts to style variants +- [Typography](/theme/typography) — font families, sizes, weights, and line heights +- [Effects](/theme/effects) — shadows and blur for depth and elevation -Apsara tokens follow a consistent naming pattern that makes them easy to discover and use: +## API Reference -``` ---rs-{category}-{property}-{variant}-{state} -``` +### ThemeProvider - - -### Examples - - - -## ThemeProvider Props +The `ThemeProvider` component wraps your application and manages theme state. It handles persisting the user's preference to localStorage, syncing with system preferences, and injecting the appropriate CSS variables into the document. -## useTheme Hook +### useTheme -Access and control the current theme using the `useTheme` hook: +The `useTheme` hook provides access to the current theme state and methods to change it. Use this to build theme toggles, read the resolved theme for conditional rendering, or sync with external systems. ```tsx import { useTheme } from "@raystack/apsara"; function ThemeToggle() { - const { theme, setTheme, resolvedTheme, systemTheme } = useTheme(); + const { theme, setTheme, resolvedTheme } = useTheme(); return ( + + + + ); +} +``` + +## Framework Setup -Apsara includes an optional `normalize.css` stylesheet to help ensure consistency across different browsers. Unlike a CSS reset, `normalize.css` preserves useful default styles while correcting inconsistencies in how browsers render HTML elements. +### Next.js (App Router) -If you'd like to enable it, simply import the provided stylesheet in your project: +Add the provider to your root layout: + +```tsx +// app/layout.tsx +import { ThemeProvider } from "@raystack/apsara"; +import "@raystack/apsara/style.css"; + +export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + + {children} + + + + ); +} +``` + +The `suppressHydrationWarning` attribute is required because `ThemeProvider` injects a script to prevent theme flash during hydration. + +### Vite + +Add the provider to your main entry file: + +```tsx +// main.tsx +import React from "react"; +import ReactDOM from "react-dom/client"; +import { ThemeProvider } from "@raystack/apsara"; +import "@raystack/apsara/style.css"; +import App from "./App"; + +ReactDOM.createRoot(document.getElementById("root")!).render( + + + + + +); +``` + +## Optional: Normalize CSS + +Apsara includes an optional normalize stylesheet that ensures consistent rendering across browsers while preserving useful defaults: ```ts import "@raystack/apsara/normalize.css"; +import "@raystack/apsara/style.css"; ``` -### 3. Start building +Import it before the main stylesheet if you choose to use it. -You are now ready to use Apsara components. +## Importing Icons -```jsx -import { Button } from "@raystack/apsara"; +Apsara exports a set of icons that can be imported separately: -; +```tsx +import { MagnifyingGlassIcon, Cross2Icon } from "@raystack/apsara/icons"; + + ``` + +## Importing Hooks + +Utility hooks are available from a dedicated export: + +```tsx +import { useTheme } from "@raystack/apsara/hooks"; + +function ThemeToggle() { + const { resolvedTheme, setTheme } = useTheme(); + + return ( + + ); +} +``` + +## Next Steps + +- [Theme Overview](/theme/overview) — Configure colors, spacing, and style variants +- [Button](/components/button) — Start with a common component +- [DataTable](/components/datatable) — Build data-rich interfaces diff --git a/apps/www/src/content/docs/(overview)/index.mdx b/apps/www/src/content/docs/(overview)/index.mdx index 19c9e530b..0ab0d62b8 100644 --- a/apps/www/src/content/docs/(overview)/index.mdx +++ b/apps/www/src/content/docs/(overview)/index.mdx @@ -3,7 +3,68 @@ title: Introduction description: A design system for building accessible and composable user interfaces in React. --- -Apsara is a design system that simplifies React application development. It offers a collection -of carefully crafted components that work seamlessly together, are accessible out of the box, -and help create consistent user interfaces quickly. +Apsara is an open-source React component library that provides enterprise-grade, accessible components for building complex data interfaces. Built on [Radix UI](https://www.radix-ui.com/) primitives and [Base UI](https://base-ui.com/), it combines unstyled accessibility foundations with a carefully designed visual layer powered by CSS custom properties. +## Why Apsara? + +**Accessibility first** — Every component is built on battle-tested primitives that handle ARIA attributes, focus management, and keyboard navigation correctly. You get accessible UI without the effort. + +**Consistent design language** — A unified token system ensures visual consistency across your application. Colors, spacing, typography, and effects all follow predictable patterns that adapt automatically to light and dark modes. + +**Production ready** — Components are designed for real-world applications: data tables with sorting and filtering, command palettes, multi-select comboboxes, and complex form controls that handle edge cases gracefully. + +**Minimal footprint** — No runtime CSS-in-JS. Styles are vanilla CSS with semantic tokens, keeping your bundle lean and your performance predictable. + +## Components + +Apsara provides over 50 components organized by function: + +| Category | Components | +|----------|------------| +| **Layout** | Box, Flex, Grid, Container, Separator | +| **Navigation** | Navbar, Sidebar, Breadcrumb, Tabs, Link | +| **Data Display** | DataTable, Table, List, Avatar, Badge, Chip, Indicator | +| **Forms** | Button, InputField, TextArea, Select, Combobox, Checkbox, Radio, Switch, Slider, ColorPicker, Calendar | +| **Feedback** | Dialog, Sheet, Popover, Tooltip, Toast, Callout, EmptyState, Skeleton, Spinner | +| **Utilities** | Command, Search, CopyButton, CodeBlock, ScrollArea | + +## Theming + +The theming system uses CSS custom properties (tokens) that automatically adapt to the active theme. Wrap your app with `ThemeProvider` to enable light/dark modes, accent colors, and style variants. + +```tsx +import { ThemeProvider } from "@raystack/apsara"; + + + + +``` + +Tokens follow a consistent naming convention: + +```css +.custom-element { + color: var(--rs-color-foreground-base-primary); + background: var(--rs-color-background-base-secondary); + padding: var(--rs-space-4); + border-radius: var(--rs-radius-3); +} +``` + +See the [Theme Overview](/theme/overview) for complete documentation. + +## Technology + +Apsara is built with: + +- **[Radix UI](https://www.radix-ui.com/)** — Unstyled, accessible component primitives +- **[Base UI](https://base-ui.com/)** — Headless UI components from MUI +- **[TanStack Table](https://tanstack.com/table)** — Powerful data table utilities +- **[class-variance-authority](https://cva.style/)** — Type-safe component variants +- **TypeScript** — Full type definitions for all components and props + +## Next Steps + +- [Getting Started](/getting-started) — Install Apsara and build your first component +- [Theme Overview](/theme/overview) — Learn about the theming system +- [Components](/components/button) — Explore the component library diff --git a/apps/www/src/content/docs/components/fliter-chip/demo.ts b/apps/www/src/content/docs/components/filter-chip/demo.ts similarity index 100% rename from apps/www/src/content/docs/components/fliter-chip/demo.ts rename to apps/www/src/content/docs/components/filter-chip/demo.ts diff --git a/apps/www/src/content/docs/components/fliter-chip/index.mdx b/apps/www/src/content/docs/components/filter-chip/index.mdx similarity index 100% rename from apps/www/src/content/docs/components/fliter-chip/index.mdx rename to apps/www/src/content/docs/components/filter-chip/index.mdx diff --git a/apps/www/src/content/docs/components/fliter-chip/props.ts b/apps/www/src/content/docs/components/filter-chip/props.ts similarity index 100% rename from apps/www/src/content/docs/components/fliter-chip/props.ts rename to apps/www/src/content/docs/components/filter-chip/props.ts From 8b72c6564917e1663ca3f1712ebaafc83f537677 Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Wed, 4 Feb 2026 09:49:57 -0600 Subject: [PATCH 6/8] docs: add scale token pattern and fix overlay color values - Document both semantic and scale token naming patterns in overview - Update overlay colors to show actual rgba values instead of percentages for consistency with other token tables --- .../src/content/docs/theme/colors/index.mdx | 48 +++++++++---------- .../src/content/docs/theme/overview/index.mdx | 8 +++- 2 files changed, 31 insertions(+), 25 deletions(-) diff --git a/apps/www/src/content/docs/theme/colors/index.mdx b/apps/www/src/content/docs/theme/colors/index.mdx index 88ebbbd0b..d8782da34 100644 --- a/apps/www/src/content/docs/theme/colors/index.mdx +++ b/apps/www/src/content/docs/theme/colors/index.mdx @@ -98,30 +98,30 @@ Overlay colors are used for modals, tooltips, and layered elements. type="color" tokens={[ { name: "--rs-color-overlay-base-primary", description: "Default overlay" }, - { name: "--rs-color-overlay-black-a1", value: "5%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a2", value: "10%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a3", value: "15%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a4", value: "20%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a5", value: "30%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a6", value: "40%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a7", value: "50%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a8", value: "60%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a9", value: "70%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a10", value: "80%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a11", value: "90%", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a12", value: "95%", description: "Black overlay" }, - { name: "--rs-color-overlay-white-a1", value: "5%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a2", value: "10%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a3", value: "15%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a4", value: "20%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a5", value: "30%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a6", value: "40%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a7", value: "50%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a8", value: "60%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a9", value: "70%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a10", value: "80%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a11", value: "90%", description: "White overlay" }, - { name: "--rs-color-overlay-white-a12", value: "95%", description: "White overlay" }, + { name: "--rs-color-overlay-black-a1", value: "rgba(0,0,0,0.05)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a2", value: "rgba(0,0,0,0.1)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a3", value: "rgba(0,0,0,0.15)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a4", value: "rgba(0,0,0,0.2)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a5", value: "rgba(0,0,0,0.3)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a6", value: "rgba(0,0,0,0.4)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a7", value: "rgba(0,0,0,0.5)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a8", value: "rgba(0,0,0,0.6)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a9", value: "rgba(0,0,0,0.7)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a10", value: "rgba(0,0,0,0.8)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a11", value: "rgba(0,0,0,0.9)", description: "Black overlay" }, + { name: "--rs-color-overlay-black-a12", value: "rgba(0,0,0,0.95)", description: "Black overlay" }, + { name: "--rs-color-overlay-white-a1", value: "rgba(255,255,255,0.05)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a2", value: "rgba(255,255,255,0.1)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a3", value: "rgba(255,255,255,0.15)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a4", value: "rgba(255,255,255,0.2)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a5", value: "rgba(255,255,255,0.3)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a6", value: "rgba(255,255,255,0.4)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a7", value: "rgba(255,255,255,0.5)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a8", value: "rgba(255,255,255,0.6)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a9", value: "rgba(255,255,255,0.7)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a10", value: "rgba(255,255,255,0.8)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a11", value: "rgba(255,255,255,0.9)", description: "White overlay" }, + { name: "--rs-color-overlay-white-a12", value: "rgba(255,255,255,0.95)", description: "White overlay" }, ]} /> diff --git a/apps/www/src/content/docs/theme/overview/index.mdx b/apps/www/src/content/docs/theme/overview/index.mdx index 48ea739f5..5d72b418b 100644 --- a/apps/www/src/content/docs/theme/overview/index.mdx +++ b/apps/www/src/content/docs/theme/overview/index.mdx @@ -40,12 +40,18 @@ See [API Reference](#api-reference) for all available props and options. ## Tokens -Tokens follow a consistent naming pattern: +Tokens follow two naming patterns: +**Semantic tokens** — for context-aware values that adapt to theme: ``` --rs-{category}-{property}-{variant}-{state} ``` +**Scale tokens** — for numerical progressions: +``` +--rs-{category}-{step} +``` + **Examples:** - `--rs-color-foreground-base-primary` — primary text color - `--rs-color-background-accent-emphasis` — accent button background From f391b9e83f64de62b2fcaf88aaba89aecf669767 Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Wed, 4 Feb 2026 10:02:10 -0600 Subject: [PATCH 7/8] docs: use flexible column width and improve overlay token descriptions - Change TokenTable value column from fixed width to min-width for better adaptability - Move overlay opacity values to descriptions for consistency with other color sections --- .../tokentable/tokentable.module.css | 4 +- .../src/content/docs/theme/colors/index.mdx | 48 +++++++++---------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/apps/www/src/components/tokentable/tokentable.module.css b/apps/www/src/components/tokentable/tokentable.module.css index 5f6067f2f..cc2483b4d 100644 --- a/apps/www/src/components/tokentable/tokentable.module.css +++ b/apps/www/src/components/tokentable/tokentable.module.css @@ -43,7 +43,7 @@ } .valueLabel { - width: 120px; + min-width: 80px; flex-shrink: 0; } @@ -104,7 +104,7 @@ } .valueCell { - width: 120px; + min-width: 80px; flex-shrink: 0; } diff --git a/apps/www/src/content/docs/theme/colors/index.mdx b/apps/www/src/content/docs/theme/colors/index.mdx index d8782da34..554e87f22 100644 --- a/apps/www/src/content/docs/theme/colors/index.mdx +++ b/apps/www/src/content/docs/theme/colors/index.mdx @@ -98,30 +98,30 @@ Overlay colors are used for modals, tooltips, and layered elements. type="color" tokens={[ { name: "--rs-color-overlay-base-primary", description: "Default overlay" }, - { name: "--rs-color-overlay-black-a1", value: "rgba(0,0,0,0.05)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a2", value: "rgba(0,0,0,0.1)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a3", value: "rgba(0,0,0,0.15)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a4", value: "rgba(0,0,0,0.2)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a5", value: "rgba(0,0,0,0.3)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a6", value: "rgba(0,0,0,0.4)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a7", value: "rgba(0,0,0,0.5)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a8", value: "rgba(0,0,0,0.6)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a9", value: "rgba(0,0,0,0.7)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a10", value: "rgba(0,0,0,0.8)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a11", value: "rgba(0,0,0,0.9)", description: "Black overlay" }, - { name: "--rs-color-overlay-black-a12", value: "rgba(0,0,0,0.95)", description: "Black overlay" }, - { name: "--rs-color-overlay-white-a1", value: "rgba(255,255,255,0.05)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a2", value: "rgba(255,255,255,0.1)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a3", value: "rgba(255,255,255,0.15)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a4", value: "rgba(255,255,255,0.2)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a5", value: "rgba(255,255,255,0.3)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a6", value: "rgba(255,255,255,0.4)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a7", value: "rgba(255,255,255,0.5)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a8", value: "rgba(255,255,255,0.6)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a9", value: "rgba(255,255,255,0.7)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a10", value: "rgba(255,255,255,0.8)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a11", value: "rgba(255,255,255,0.9)", description: "White overlay" }, - { name: "--rs-color-overlay-white-a12", value: "rgba(255,255,255,0.95)", description: "White overlay" }, + { name: "--rs-color-overlay-black-a1", description: "Black overlay at 5% opacity" }, + { name: "--rs-color-overlay-black-a2", description: "Black overlay at 10% opacity" }, + { name: "--rs-color-overlay-black-a3", description: "Black overlay at 15% opacity" }, + { name: "--rs-color-overlay-black-a4", description: "Black overlay at 20% opacity" }, + { name: "--rs-color-overlay-black-a5", description: "Black overlay at 30% opacity" }, + { name: "--rs-color-overlay-black-a6", description: "Black overlay at 40% opacity" }, + { name: "--rs-color-overlay-black-a7", description: "Black overlay at 50% opacity" }, + { name: "--rs-color-overlay-black-a8", description: "Black overlay at 60% opacity" }, + { name: "--rs-color-overlay-black-a9", description: "Black overlay at 70% opacity" }, + { name: "--rs-color-overlay-black-a10", description: "Black overlay at 80% opacity" }, + { name: "--rs-color-overlay-black-a11", description: "Black overlay at 90% opacity" }, + { name: "--rs-color-overlay-black-a12", description: "Black overlay at 95% opacity" }, + { name: "--rs-color-overlay-white-a1", description: "White overlay at 5% opacity" }, + { name: "--rs-color-overlay-white-a2", description: "White overlay at 10% opacity" }, + { name: "--rs-color-overlay-white-a3", description: "White overlay at 15% opacity" }, + { name: "--rs-color-overlay-white-a4", description: "White overlay at 20% opacity" }, + { name: "--rs-color-overlay-white-a5", description: "White overlay at 30% opacity" }, + { name: "--rs-color-overlay-white-a6", description: "White overlay at 40% opacity" }, + { name: "--rs-color-overlay-white-a7", description: "White overlay at 50% opacity" }, + { name: "--rs-color-overlay-white-a8", description: "White overlay at 60% opacity" }, + { name: "--rs-color-overlay-white-a9", description: "White overlay at 70% opacity" }, + { name: "--rs-color-overlay-white-a10", description: "White overlay at 80% opacity" }, + { name: "--rs-color-overlay-white-a11", description: "White overlay at 90% opacity" }, + { name: "--rs-color-overlay-white-a12", description: "White overlay at 95% opacity" }, ]} /> From 9393736395977b58b063b158fc289365d2282ad2 Mon Sep 17 00:00:00 2001 From: Ravi Suhag Date: Wed, 4 Feb 2026 11:02:46 -0600 Subject: [PATCH 8/8] docs: use Apsara CopyButton and fix getting-started examples - Replace custom CopyButton with Apsara's CopyButton component in TokenTable - Remove duplicate stylesheet import from ThemeProvider example - Add missing Button imports to icons and hooks examples --- .../tokentable/tokentable.module.css | 26 ++---------- .../src/components/tokentable/tokentable.tsx | 40 +++---------------- .../docs/(overview)/getting-started.mdx | 3 +- 3 files changed, 12 insertions(+), 57 deletions(-) diff --git a/apps/www/src/components/tokentable/tokentable.module.css b/apps/www/src/components/tokentable/tokentable.module.css index cc2483b4d..2174162bc 100644 --- a/apps/www/src/components/tokentable/tokentable.module.css +++ b/apps/www/src/components/tokentable/tokentable.module.css @@ -135,34 +135,16 @@ } .copyButton { - display: inline-flex; - align-items: center; - justify-content: center; - width: 24px; - height: 24px; - padding: 0; - border: none; - background: transparent; - color: var(--rs-color-foreground-base-tertiary); - cursor: pointer; - border-radius: var(--rs-radius-2); - transition: all 0.15s ease; opacity: 0; + transition: opacity 0.15s ease; } -.row:hover .copyButton { +.row:hover .copyButton, +.row:focus-within .copyButton, +.copyButton:focus-visible { opacity: 1; } -.copyButton:hover { - background: var(--rs-color-background-neutral-secondary); - color: var(--rs-color-foreground-base-primary); -} - -.copyIconSuccess { - color: var(--rs-color-foreground-success-primary); -} - /* Preview styles */ .colorPreview { width: 24px; diff --git a/apps/www/src/components/tokentable/tokentable.tsx b/apps/www/src/components/tokentable/tokentable.tsx index 40219023c..7e4f02bc8 100644 --- a/apps/www/src/components/tokentable/tokentable.tsx +++ b/apps/www/src/components/tokentable/tokentable.tsx @@ -1,9 +1,7 @@ 'use client'; -import { Flex, Text, Tooltip } from '@raystack/apsara'; +import { CopyButton, Flex, Text } from '@raystack/apsara'; import { cx } from 'class-variance-authority'; -import { CheckIcon, CopyIcon } from 'lucide-react'; -import { type ReactNode, useCallback, useState } from 'react'; import styles from './tokentable.module.css'; export type TokenType = @@ -33,36 +31,6 @@ export interface TokenTableProps { className?: string; } -function CopyButton({ text }: { text: string }) { - const [copied, setCopied] = useState(false); - - const handleCopy = useCallback(async () => { - try { - await navigator.clipboard.writeText(text); - setCopied(true); - setTimeout(() => setCopied(false), 2000); - } catch (err) { - console.error('Failed to copy:', err); - } - }, [text]); - - return ( - - - - ); -} - function TokenPreview({ token, type }: { token: TokenItem; type: TokenType }) { switch (type) { case 'color': @@ -153,7 +121,11 @@ export function TokenTable({ > {token.name} - + {showValue && ( diff --git a/apps/www/src/content/docs/(overview)/getting-started.mdx b/apps/www/src/content/docs/(overview)/getting-started.mdx index 16e670b8e..e1bd838cb 100644 --- a/apps/www/src/content/docs/(overview)/getting-started.mdx +++ b/apps/www/src/content/docs/(overview)/getting-started.mdx @@ -38,7 +38,6 @@ Wrap your application with `ThemeProvider` to enable theming support: ```tsx import { ThemeProvider } from "@raystack/apsara"; -import "@raystack/apsara/style.css"; function App() { return ( @@ -134,6 +133,7 @@ Import it before the main stylesheet if you choose to use it. Apsara exports a set of icons that can be imported separately: ```tsx +import { Button } from "@raystack/apsara"; import { MagnifyingGlassIcon, Cross2Icon } from "@raystack/apsara/icons"; @@ -144,6 +144,7 @@ import { MagnifyingGlassIcon, Cross2Icon } from "@raystack/apsara/icons"; Utility hooks are available from a dedicated export: ```tsx +import { Button } from "@raystack/apsara"; import { useTheme } from "@raystack/apsara/hooks"; function ThemeToggle() {