Visual Components UI Library

This package contains the shared UI component library used across Visual Components applications.

Use this guide as a quick starting point to understand where things are before diving into implementation details.

Start Here (First-Time Users)

If you are new to this package, use this order:

1. Read this file for a high-level map.
2. Open src/index.ts to see what is publicly exported.
3. Browse src/components/ for available building blocks.
4. Check THEME_INTEGRATION.md to understand theming setup.
5. Review src/tokens/ if you need to work with design tokens.

High-Level Project Map

Core entry points

• src/index.ts
  • Public exports for consumers of the UI package.
• src/_internal/
  • Internal-only exports and helpers that are not part of the stable public API.

UI building blocks

• src/components/
  • Reusable UI primitives and composed components (for example: Button, Dialog, Card, Grid, etc.).
  • Each component folder typically contains implementation and related files for that component.

Theme and styling

• src/themes/
  • Theme definitions and theme-related configuration.
• THEME_INTEGRATION.md
  • Practical guidance for integrating the UI theme in consuming apps.

Tokens

• src/tokens/
  • Token release system, validators, and brand/versioned token artifacts.
  • Use this area when working on design token imports, validation, and release flow.

Icons

• src/icons/
  • Icon assets/components used by the UI library.

Packaging and build

• tsup.config.ts
  • Build configuration for package outputs.
• package.json
  • Scripts, dependencies, and package metadata.

Common Contributor Paths

• Add or update a component: start in src/components/<ComponentName>/
• Adjust theme behavior: start in src/themes/ and THEME_INTEGRATION.md
• Work with design tokens: start in src/tokens/
• Adjust public exports: start in src/index.ts

Notes

• Keep public API changes intentional and update exports in src/index.ts explicitly.
• Prefer adding docs next to major feature changes (component, theme, or token behavior).