DOCSEARCHbyAlgolia
Submit Docs

Frosted UI Design System

repository·main·Indexed 42 days ago

https://github.com/whopio/frosted-ui

A design system optimized for React Native providing themed components, semantic colors, and responsive layout patterns. Includes packages for React Native, colors, and icons, as well as a Figma Icon Sync plugin for bridging design assets to GitHub Actions.

Tokens
33.9K
Snippets
133
Records
198
Agent score
55%

What's inside Frosted UI

  1. Overview of Lightbox Component Architecture

    main

    The Lightbox component is a modular media viewer composed of several specialized sub-components. It supports View Transitions (VT), keyboard navigation, and a dialog-based modal structure.

    Core File Inventory:

    • lightbox.ts: Public API surface (barrel export).
    • index.ts: Re-exports the components under the Lightbox namespace.
    • lightbox-root.tsx: The state provider that orchestrates opening/closing and View Transition morph logic.
    • lightbox-content.tsx: Renders the native <dialog> modal, handles keyboard navigation, and backdrop clicks.
    • lightbox-item.tsx: Represents individual media items with lazy rendering and caption support.
    • lightbox-item-group.tsx: Container for items that manages the preload window and direction tracking.
    • lightbox-trigger.tsx: The button used to open the lightbox for a specific index.
    • lightbox-close.tsx, lightbox-previous.tsx, lightbox-next.tsx: Navigation and dismissal controls.
    • lightbox-counter.tsx: Displays the current position (e.g., "1 / 12") using aria-live.
    • lightbox-caption.tsx: Displays the caption for the currently active item.
    • lightbox-thumbnail-group.tsx: A tablist container for thumbnail navigation using roving tabindex.

  2. How the Icon Sync workflow works

    main

    The plugin acts as a validator and bridge to GitHub Actions. It does not store or transmit credentials.

    1. Validation: The plugin inspects the Figma file to ensure icons follow naming, sizing, and structure conventions.
    2. Sync Trigger: Once all errors are resolved, an Open sync on GitHub button becomes enabled.
    3. GitHub Execution: Clicking the button opens the Sync Icons from Figma workflow page in your browser. You then use GitHub's native Run workflow button to execute the sync.

    Authentication and permissions are handled entirely by GitHub's existing repository access controls.

  3. How the pictogram 'auto' variant works

    main

    The variant="auto" setting uses the CSS light-dark() function. This allows the icon to switch colors based on the browser's color-scheme without requiring React state or media query listeners, preventing hydration mismatches.

    Requirements:

    • The parent element (or :root) must have a color-scheme declaration (e.g., color-scheme: light dark;).
    • In a frosted-ui app, the Theme component handles this automatically.

    Browser Support: light-dark() is supported in modern browsers (Chrome 123, Safari 17.5, Firefox 120). For older browsers, the auto variant may fail to render a fill; in those cases, explicitly pin the variant using variant="light" or variant="dark".

  4. Use shared base tsconfigs

    main
    The tsconfig package provides base shared tsconfig.json files designed to be used as the foundation for all other TypeScript configurations within the monorepo. To use them, extend these base configurations in your own tsconfig.json files to ensure consistent compiler settings across the project.

  5. Control Lightbox state via Props or Ref

    main

    The Lightbox supports two primary patterns for controlling its state:

    1. Controlled Pattern: Use value, defaultValue, and onValueChange props to manage the active item index. This is consistent with patterns found in Radix and Base UI.
    2. Uncontrolled/Imperative Pattern: Use the LightboxRootRef to call imperative methods like .open(index?), .close(), and .goTo(index). This is primarily intended for uncontrolled usage or for triggering actions from outside the React tree.

  6. Configure Select positioning with `alignItemWithTrigger`

    main

    Base UI Select defaults to overlapping the trigger so the selected item aligns with the trigger text. To achieve standard dropdown behavior (where the menu appears below/above the trigger), set alignItemWithTrigger={false} on the Select.Positioner component.

    • Default behavior: alignItemWithTrigger={true} (Item-aligned).
    • Popper behavior: alignItemWithTrigger={false} (Standard dropdown).

  10. Migrate Select from Radix UI to Base UI

    main

    When migrating the Select component from Radix UI to Base UI, you must update the component structure and prop signatures. Base UI uses a more explicit compound component pattern.

    Component Mapping

    Radix UIBase UINotes
    Select.RootSelect.RootAdds items prop for value formatting
    Select.TriggerSelect.Trigger + Select.Value + Select.IconCompound structure
    Select.ContentSelect.Portal + Select.Positioner + Select.Popup + Select.ListInternal structure change
    Select.ItemSelect.Item + Select.ItemIndicator + Select.ItemTextExplicit children
    Select.GroupSelect.GroupSimilar
    Select.LabelSelect.GroupLabelMust be inside Group
    Select.SeparatorSelect.SeparatorSimilar
    Select.ViewportSelect.ListRenamed

    Breaking Changes

    1. asChild is removed: Select.Trigger no longer accepts asChild. Instead, it uses a compound structure containing Select.Value.
    2. position prop is removed: Use alignItemWithTrigger on the Positioner instead.
      • position="item-aligned" (Radix default) $\rightarrow$ alignItemWithTrigger={true} (Base UI default).
      • position="popper" $\rightarrow$ alignItemWithTrigger={false}.
    3. Label placement: Select.GroupLabel (formerly Select.Label) must now be placed inside a Select.Group.
    4. onValueChange signature: The callback now provides two arguments: (value, event) => void instead of just (value) => void.

  11. Regenerate the Emoji Color Map

    main

    The emoji-to-color mappings are pre-computed. You should regenerate them if:

    • New emojis are added to Unicode.
    • The color palette values change (added, removed, or renamed).
    • You adjust the color detection algorithm.

    To regenerate the mappings, run the following command from the packages/frosted-ui directory:

    pnpm generate:emoji-colors

    This updates the generated file at src/helpers/emoji-colors.ts.

    cd packages/frosted-ui
pnpm generate:emoji-colors