@duyluonganduin/acl-web-components 0.0.1

package/README.md

@@ -0,0 +1,187 @@
+# acl-web-components
+
+A native Web Components library built with [Lit](https://lit.dev) and TypeScript for the Anduin design system.
+
+## Installation
+
+```bash
+npm install acl-web-components
+```
+
+---
+
+## Setup
+
+### 1. Import the components
+
+```js
+import '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.
+
+```css
+@import 'acl-web-components/tokens.css';
+```
+
+Or in JS:
+
+```js
+import 'acl-web-components/tokens.css'
+```
+
+---
+
+## Tailwind Integration
+
+### Tailwind v3
+
+Add the preset to extend your Tailwind theme with all design tokens:
+
+```js
+// tailwind.config.js
+import aclPreset from 'acl-web-components/tailwind-preset'
+
+export default {
+  presets: [aclPreset],
+  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
+}
+```
+
+```css
+/* main.css */
+@import 'acl-web-components/tokens.css';
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+### Tailwind v4
+
+Import the CSS theme bridge instead of a config preset:
+
+```css
+/* main.css */
+@import "tailwindcss";
+@import "acl-web-components/tokens.css";
+@import "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:
+
+```html
+<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.
+
+```html
+<acl-button appearance="filled" variant="primary">Save</acl-button>
+<acl-input placeholder="Search..." />
+<acl-spinner size="small"></acl-spinner>
+```
+
+### Framework integration
+
+**React:**
+
+```jsx
+import 'acl-web-components'
+import 'acl-web-components/tokens.css'
+
+export default function App() {
+  return (
+    <div>
+      <acl-button appearance="filled" variant="primary">Click me</acl-button>
+      <acl-input placeholder="Enter text..." />
+    </div>
+  )
+}
+```
+
+**Vue:**
+
+```vue
+<script setup>
+import 'acl-web-components'
+import 'acl-web-components/tokens.css'
+</script>
+
+<template>
+  <acl-button appearance="filled" variant="primary">Click me</acl-button>
+  <acl-input placeholder="Enter text..." />
+</template>
+```
+
+---
+
+## Component Reference
+
+| Component | Tag | Key Attributes |
+|---|---|---|
+| Badge | `<acl-badge>` | `variant` |
+| Badge Count | `<acl-badge-count>` | `variant`, `count` |
+| Button | `<acl-button>` | `appearance`, `variant` (default: `gray0`), `size`, `disabled`, `loading`, `href`, `pill`, `full-width`, `start-icon`, `end-icon` |
+| Callout | `<acl-callout>` | `variant` |
+| Checkbox | `<acl-checkbox>` | `checked`, `disabled`, `indeterminate`, `readonly`, `inputid` |
+| Divider | `<acl-divider>` | `direction` |
+| Dot | `<acl-dot>` | `variant` |
+| Field | `<acl-field>` | `orientation` |
+| Field Label | `<acl-field-label>` | `htmlfor`, `required` |
+| Icon | `<acl-icon>` | `name`, `size` (12 small · **16 default** · 20 · 24 large) |
+| Input | `<acl-input>` | `value`, `size`, `disabled`, `readonly`, `placeholder`, `inputid`, `status` |
+| Loading State | `<acl-loading-state>` | `height` |
+| Progress | `<acl-progress>` | `percent`, `height` |
+| Skeleton | `<acl-skeleton>` | `effect`, `shape`, `height`, `width`, `duration`, `font-size` |
+| Spinner | `<acl-spinner>` | `size`, `percent` |
+| Tabs | `<acl-tabs>` | `default-value`, `value` |
+| Tab List | `<acl-tabs-list>` | `alignment` |
+| Tab Trigger | `<acl-tab-trigger>` | `value`, `start-icon`, `disabled` |
+| Tab Content | `<acl-tab-content>` | `value` |
+| Tag | `<acl-tag>` | `variant`, `icon`, `disabled` |
+| Textarea | `<acl-textarea>` | `value`, `disabled`, `readonly`, `placeholder`, `inputid`, `rows`, `status` |
+| Tooltip | `<acl-tooltip>` | `placement`, `disabled` |
+| Tooltip Trigger | `<acl-tooltip-trigger>` | — |
+| Tooltip Content | `<acl-tooltip-content>` | — |
+| Well | `<acl-well>` | `variant` |
+
+---
+
+## Package Exports
+
+| Import path | Contents |
+|---|---|
+| `acl-web-components` | All component classes (auto-registers custom elements) |
+| `acl-web-components/tokens.css` | CSS custom properties for all design tokens |
+| `acl-web-components/tailwind-preset` | Tailwind **v3** preset |
+| `acl-web-components/tailwind-theme.css` | Tailwind **v4** `@theme inline` bridge |
+
+---
+
+## Development
+
+```bash
+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](https://lit.dev) — Web Components base library
+- [Vite](https://vitejs.dev) — Build tool (library mode)
+- [Storybook](https://storybook.js.org) — Component development & documentation
+- TypeScript