acl-web-components

A native Web Components library built with Lit and TypeScript for the Anduin design system.

Installation

npm i @duyluonganduin/acl-web-components

Setup

1. Import the components

import '@duyluonganduin/acl-web-components'

2. Import design tokens (required)

The tokens file sets all CSS custom properties (--color-*, --text-*, etc.) on :root. It must be imported once at your app root.

@import '@duyluonganduin/acl-web-components/tokens.css';

Or in JS:

import '@duyluonganduin/acl-web-components/tokens.css'

Tailwind Integration

Tailwind v3

Add the preset to extend your Tailwind theme with all design tokens:

// tailwind.config.js
import aclPreset from '@duyluonganduin/acl-web-components/tailwind-preset'

export default {
  presets: [aclPreset],
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
}

/* main.css */
@import '@duyluonganduin/acl-web-components/tokens.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind v4

Import the CSS theme bridge instead of a config preset:

/* main.css */
@import "tailwindcss";
@import "@duyluonganduin/acl-web-components/tokens.css";
@import "@duyluonganduin/acl-web-components/tailwind-theme.css";

No tailwind.config.js changes needed.

Using token-based utility classes

Once set up, you can use token values directly as Tailwind classes:

<p class="text-13 font-medium text-primary-4 leading-20">Heading</p>
<div class="bg-gray-1 rounded-lg shadow-2 p-16 gap-8 flex">...</div>
<span class="text-danger-4 font-semibold">Error message</span>

Components

Use components directly in HTML — they work in any framework since they are standard custom elements.

<anduin-button appearance="filled" variant="primary">Save</anduin-button>
<anduin-input placeholder="Search..."></anduin-input>
<anduin-spinner size="small"></anduin-spinner>

Framework integration

React:

import '@duyluonganduin/acl-web-components'
import '@duyluonganduin/acl-web-components/tokens.css'

export default function App() {
  return (
    <div>
      <anduin-button appearance="filled" variant="primary">Click me</anduin-button>
      <anduin-input placeholder="Enter text..."></anduin-input>
    </div>
  )
}

Vue:

<script setup>
import '@duyluonganduin/acl-web-components'
import '@duyluonganduin/acl-web-components/tokens.css'
</script>

<template>
  <anduin-button appearance="filled" variant="primary">Click me</anduin-button>
  <anduin-input placeholder="Enter text..."></anduin-input>
</template>

TypeScript + React — JSX types

The package ships dist/react.d.ts which augments React.JSX.IntrinsicElements so TypeScript accepts all anduin-* elements in .tsx files without errors.

Enable it in one of two ways:

Option A — tsconfig.json (recommended, applies project-wide):

{
  "compilerOptions": {
    "types": ["@duyluonganduin/acl-web-components/react"]
  }
}

Option B — reference directive (per-file or in a global .d.ts):

/// <reference types="@duyluonganduin/acl-web-components/react" />

Once enabled, all component props are typed:

<anduin-button appearance="filled" variant="primary" disabled>
  Save
</anduin-button>

<anduin-input value={query} placeholder="Search..." status="valid"></anduin-input>

Component Reference

| Component | Tag | Key Attributes | |---|---|---| | Badge | <anduin-badge> | variant | | Badge Count | <anduin-badge-count> | variant, count | | Button | <anduin-button> | appearance, variant (default: gray0), size, disabled, loading, href, pill, full-width, start-icon, end-icon | | Callout | <anduin-callout> | variant | | Checkbox | <anduin-checkbox> | checked, disabled, indeterminate, readonly, inputid | | Divider | <anduin-divider> | direction | | Dot | <anduin-dot> | variant | | Field | <anduin-field> | orientation | | Field Label | <anduin-field-label> | htmlfor, required | | Field Description | <anduin-field-description> | — | | Field Error | <anduin-field-error> | — | | Field Group | <anduin-field-group> | — | | Icon | <anduin-icon> | name, size (12 small · 16 default · 20 · 24 large) | | Input | <anduin-input> | value, size, disabled, readonly, placeholder, inputid, status | | Loading State | <anduin-loading-state> | height | | Progress | <anduin-progress> | percent, height | | Skeleton | <anduin-skeleton> | effect, shape, height, width, duration, font-size | | Spinner | <anduin-spinner> | size, percent | | Menu | <anduin-menu> | placement, open | | Menu Item | <anduin-menu-item> | icon, variant, disabled | | Popover | <anduin-popover> | placement, open | | Tabs | <anduin-tabs> | default-value, value, fill | | Tab List | <anduin-tabs-list> | alignment | | Tab Trigger | <anduin-tab-trigger> | value, start-icon, disabled, show-badge, badge-count | | Tab Content | <anduin-tab-content> | value | | Tag | <anduin-tag> | variant, icon, disabled | | Tag Close | <anduin-tag-close> | — | | Textarea | <anduin-textarea> | value, disabled, readonly, placeholder, inputid, rows, status | | Tooltip | <anduin-tooltip> | placement, disabled | | Tooltip Trigger | <anduin-tooltip-trigger> | — | | Tooltip Content | <anduin-tooltip-content> | — | | Well | <anduin-well> | variant | | Well Close | <anduin-well-close> | — |

Package Exports

| Import path | Contents | |---|---| | @duyluonganduin/acl-web-components | All component classes (auto-registers custom elements) | | @duyluonganduin/acl-web-components/tokens.css | CSS custom properties for all design tokens | | @duyluonganduin/acl-web-components/tailwind-preset | Tailwind v3 preset | | @duyluonganduin/acl-web-components/tailwind-theme.css | Tailwind v4 @theme inline bridge | | @duyluonganduin/acl-web-components/react | React JSX types (IntrinsicElements for all anduin-* elements) |

Development

npm install
npm run storybook        # Component dev server → http://localhost:6006
npm run build            # Type-check + Vite build → dist/
npm run build-storybook  # Static Storybook export

Stack

• Lit — Web Components base library
• Vite — Build tool (library mode)
• Storybook — Component development & documentation
• TypeScript