docs: create docs for apsara tokens #574
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
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.
- 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
- 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
- Add comprehensive introduction page with value props, component overview, theming guide, and technology stack - Expand getting started with prerequisites, framework setup guides for Next.js and Vite, and additional sections for icons and hooks imports - Rename fliter-chip to filter-chip to fix directory name typo
- 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
|
Note Currently processing new changes in this PR. This may take a few minutes, please wait... ✏️ Tip: You can disable in-progress messages and the fortune message in your review settings. Tip You can customize the tone of the review comments and chat replies.Set the 📝 WalkthroughWalkthroughThis change adds a new client-side TokenTable component (with styles and re-exports), integrates it into MDX components, introduces prose table CSS, and adds extensive theme documentation pages (overview, colors, effects, radius, spacing, typography) plus theme-related types and metadata updates. Changes
Sequence Diagram(s)sequenceDiagram
participant User as User
participant UI as TokenTable (React)
participant CB as Clipboard API
participant Tip as Tooltip/State
User->>UI: Click copy button for a token
UI->>CB: writeText("var(--token-name)")
CB-->>UI: success / failure
UI->>Tip: show "Copied!" feedback (2s) / show error
Tip-->>User: visual confirmation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~35 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In `@apps/www/src/components/tokentable/tokentable.tsx`:
- Around line 49-55: Add an explicit type='button' to the copy button and guard
clipboard availability: detect clipboard support (e.g., check typeof navigator
!== 'undefined' && navigator.clipboard && typeof navigator.clipboard.writeText
=== 'function') in the Tokentable component (where handleCopy is defined),
disable the button and adjust aria attributes when unsupported, and have
handleCopy early-return if the clipboard API is unavailable; this prevents
accidental form submission and avoids enabling the button in environments that
don't support navigator.clipboard.
- Around line 36-47: The CopyButton component's setTimeout can run after unmount
and cause state updates on an unmounted component; modify CopyButton to use a
ref (e.g., timeoutRef) to store the timeout id, clear any existing timeout
before creating a new one, and add a useEffect cleanup that clears
timeoutRef.current on unmount; update the handleCopy logic in CopyButton to
clear timeoutRef.current before calling setTimeout and assign the id to
timeoutRef.current so it can be cancelled in the cleanup.
In `@apps/www/src/content/docs/`(overview)/getting-started.mdx:
- Around line 35-52: Remove the duplicate stylesheet import from the Step 2
snippet: keep only the ThemeProvider import and usage (import { ThemeProvider }
from "@raystack/apsara"; and the ThemeProvider wrapper around <YourApp />),
since the global stylesheet import (import "@raystack/apsara/style.css") is
already shown in Step 1 and should only be included once at the app root; update
the Step 2 code block to omit the redundant import and ensure the documentation
text still notes that the stylesheet is required at the application root.
- Around line 132-158: The two examples render the Button component but don't
import it; update both snippets to import Button alongside the other named
exports (e.g., add Button to the import list where
MagnifyingGlassIcon/Cross2Icon are imported and where useTheme is used), so that
the icons example (MagnifyingGlassIcon, Cross2Icon) and the hooks example
(ThemeToggle using useTheme) include an import like import { Button, ... } from
"@raystack/apsara" to make the snippets complete and runnable.
In `@apps/www/src/content/docs/`(overview)/index.mdx:
- Line 14: The phrase "Production ready" in the sentence starting with that
phrase should be hyphenated as "Production-ready" when used as a compound
adjective before a noun; update the text in
apps/www/src/content/docs/(overview)/index.mdx replacing "Production ready —
Components are designed..." with "Production-ready — Components are designed..."
so the compound adjective is grammatically correct.
In `@apps/www/src/content/docs/theme/overview/props.ts`:
- Line 72: The file uses the type React.ReactNode for the children prop but
never imports React; add an import from 'react' to satisfy the type usage
(either add "import React from 'react'" or "import type { ReactNode } from
'react'" and change the prop to use ReactNode) so that the declaration
"children?: React.ReactNode;" in props.ts compiles.
🧹 Nitpick comments (4)
apps/www/src/components/mdx/mdx-components.tsx (1)
124-126: Consider applying consistent className handling.The
TypeTablecomponent (lines 118-123) merges a prose-specific className, butTokenTablepasses props through without applying any additional styling. This may be intentional ifTokenTablehandles its own styling, but worth confirming consistency is desired.♻️ Optional: Apply consistent className pattern
If
TokenTableshould also receive prose-specific styling:- TokenTable: (props: ComponentPropsWithoutRef<typeof TokenTable>) => ( - <TokenTable {...props} /> - ), + TokenTable: (props: ComponentPropsWithoutRef<typeof TokenTable>) => ( + <TokenTable + {...props} + className={cx(styles['prose-type-table'], props.className)} + /> + ),apps/www/src/content/docs/theme/overview/props.ts (1)
33-33: Type union is redundant but documents intent.
string | 'class'is technically redundant since'class'is a subtype ofstring. However, it does communicate that'class'is a common/expected value. Consider using a more explicit union if specific values are preferred:♻️ Optional: More explicit type
- attribute?: string | 'class'; + attribute?: 'class' | 'data-theme' | (string & {});The
(string & {})pattern preserves autocomplete for the literal types while still accepting any string.apps/www/src/content/docs/theme/colors/index.mdx (1)
101-125: Consider adding more descriptive use cases for overlay tokens.The overlay token descriptions are generic ("Black overlay", "White overlay"). While the alpha values are self-explanatory, consider adding context about typical use cases to help developers choose the right opacity level.
For example:
a1-a3: Subtle overlays, disabled statesa4-a6: Modal backdrops (light dimming)a7-a9: Strong overlays, image darkeninga10-a12: Near-opaque overlaysapps/www/src/components/tokentable/tokentable.module.css (1)
229-255: Responsive styles may need to include wide cell variants.The responsive media query updates
.previewCelland.tokenCellbut doesn't include.previewCellWideand.tokenCellWidevariants defined in lines 84-104. If these variants are used, they may not respond correctly on mobile.♻️ Proposed fix to include wide variants in responsive styles
`@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, + .previewCellWide, .tokenCell, + .tokenCellWide, .valueCell, .descriptionCell { width: 100%; } - .previewCell { + .previewCell, + .previewCellWide { justify-content: flex-start; } .copyButton { opacity: 1; } }
- 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
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@apps/www/src/components/tokentable/tokentable.module.css`:
- Around line 137-160: The copy button is only revealed on row hover, so
keyboard users can tab to an invisible control; update the CSS selectors around
.copyButton and .row to also reveal and style the control on keyboard focus: add
rules for .copyButton:focus-visible and .row:focus-within .copyButton to set
opacity: 1 and provide a visible focus ring (e.g., outline or box-shadow with
appropriate outline-offset and border-radius) and ensure the focus ring
contrasts with background; keep existing hover styles for mouse users and reuse
the --rs-radius-2 variable for consistent rounding.
🧹 Nitpick comments (3)
apps/www/src/content/docs/theme/colors/index.mdx (3)
93-126: Overlay opacity scale is non-linear.The opacity progression jumps from 20% (a4) to 30% (a5), then continues in 10% increments. If this is intentional for design purposes, consider adding a brief note explaining the scale rationale to help users choose the appropriate overlay level.
128-150: Consider documenting the full visualization color scale or clarifying the "-9" suffix.All visualization tokens use the "-9" suffix, suggesting a larger color scale exists (likely steps 1-12). Consider either:
- Adding a note explaining why "-9" is the recommended variant for data visualization
- Documenting additional scale steps if they're available for use cases requiring lighter/darker variants
223-228: Solid best practices with room for accessibility enhancement.The guidelines are practical and well-articulated. Consider adding a best practice about ensuring sufficient color contrast ratios (WCAG AA/AAA) when combining foreground and background tokens, especially for text readability.
📝 Suggested addition
- **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 +- **Ensure sufficient contrast** - Verify that text and interactive elements meet WCAG contrast requirements (4.5:1 for normal text, 3:1 for large text)
- 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
Adds comprehensive theme documentation for Apsara design system, covering the theming system
overview and all design tokens.
Changes
New Theme Documentation Section
Created a new "Theme" section in the documentation with the following pages:
style variants, accent colors, and gray color options
overlay, and visualization colors
heights, and letter spacing
--rs-space-17)
variants
Files Added
Files Modified
Notes
Summary by CodeRabbit
New Features
Documentation
Style