@appsbd/vue3-appsbd-ui 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/.ai/ai_ref_AbButton.md +1 -2
  2. package/.ai/ai_ref_AbCard.md +70 -53
  3. package/.ai/ai_ref_AbChart.md +87 -0
  4. package/.ai/ai_ref_AbDateTimePicker.md +3 -0
  5. package/.ai/ai_ref_AbField.md +96 -93
  6. package/.ai/ai_ref_AbInputField.md +74 -71
  7. package/.ai/ai_ref_AbInputTag.md +3 -0
  8. package/.ai/ai_ref_AbMultiSelect.md +3 -0
  9. package/.ai/ai_ref_AbProgressbar.md +9 -2
  10. package/AI_REFERENCE.md +53 -100
  11. package/design-system.md +403 -0
  12. package/dist/skins/black.css +1 -1
  13. package/dist/skins/cyan.css +1 -1
  14. package/dist/skins/default.css +1 -1
  15. package/dist/skins/gray.css +1 -1
  16. package/dist/skins/green.css +1 -1
  17. package/dist/skins/orange.css +1 -1
  18. package/dist/skins/pink.css +1 -1
  19. package/dist/skins/purple.css +1 -1
  20. package/dist/skins/red.css +1 -1
  21. package/dist/skins/themes/_common_variable.scss +2 -0
  22. package/dist/skins/violet.css +1 -1
  23. package/dist/style.css +1 -1
  24. package/dist/vue3-appsbd-ui.cjs.js +114 -41
  25. package/dist/vue3-appsbd-ui.es.js +27186 -4661
  26. package/package.json +10 -4
package/AI_REFERENCE.md CHANGED
@@ -92,6 +92,7 @@ Each component also has a standalone reference under `.ai/` with installation, f
92
92
  | `AbPricingCard` | Single pricing tier card. | [.ai/ai_ref_AbPricingCard.md](./.ai/ai_ref_AbPricingCard.md) |
93
93
  | `AbPricingContainer` | Layout wrapper for pricing tables. | [.ai/ai_ref_AbPricingContainer.md](./.ai/ai_ref_AbPricingContainer.md) |
94
94
  | `AbPricingTable` | Stylized, responsive pricing table component with feature list and package columns. | [.ai/ai_ref_AbPricingTable.md](./.ai/ai_ref_AbPricingTable.md) |
95
+ | `AbChart` | Flexible chart component powered by Apache ECharts. | [.ai/ai_ref_AbChart.md](./.ai/ai_ref_AbChart.md) |
95
96
  | `AbDarkModeToggler` | Light / dark theme toggle (pairs with `useTheme`). | [.ai/ai_ref_AbDarkModeToggler.md](./.ai/ai_ref_AbDarkModeToggler.md) |
96
97
 
97
98
  ## 3. Full Component API Reference
@@ -140,7 +141,6 @@ Global configuration setter for library-wide tokens.
140
141
  | --------------------- | ------- | ----------- | ------------------------------------------------------- |
141
142
  | `type` | String | `"button"` | Native button type. |
142
143
  | `variant` | String | `"primary"` | Color variant (`primary`, `secondary`, `danger`, etc.). |
143
- | `outlineVariant` | String | `"primary"` | Color variant applied when `isOutline` is true. |
144
144
  | `size` | String | `"md"` | Button size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`). |
145
145
  | `isOutline` | Boolean | `false` | Applies the outline style for the selected variant. |
146
146
  | `isIconBtn` | Boolean | `false` | Adjusts formatting for a button with only an icon. |
@@ -168,16 +168,21 @@ Global configuration setter for library-wide tokens.
168
168
 
169
169
  **Props**
170
170
 
171
- | Name | Type | Default |
172
- | ---------------- | ------ | ------- |
173
- | `containerClass` | String | `""` |
174
- | `headerClass` | String | `""` |
175
- | `bodyClass` | String | `""` |
176
- | `footerClass` | String | `""` |
171
+ | Name | Type | Default | Notes |
172
+ | --- | --- | --- | --- |
173
+ | `containerClass` | String | `undefined` | Classes to append directly to the root card container. |
174
+ | `headerClass` | String | `""` | Classes for the header section. |
175
+ | `bodyClass` | String | `""` | Classes for the body section. |
176
+ | `footerClass` | String | `""` | Classes for the footer section. |
177
+ | `isBorderCard` | Boolean | `true` | Whether to display the default card border. |
178
+ | `bgColorVariant` | String | `""` | Bootstrap color variant for background (`primary`, `success`, etc.). |
179
+ | `borderBottomVariant` | String | `""` | Adds a colored bottom border with the specified variant. |
180
+ | `isTileCard` | Boolean | `false` | Applies the `.tile-card` layout styles. |
181
+ | `variation` | String | `""` | Generic variation class to append to the root. |
177
182
 
178
- **Slots** ? `header`, `body`, `footer`.
183
+ **Slots** — `header`, `body`, `footer`.
179
184
 
180
- **Notes** ? For layout variations (`tile-card`, `item-card`, `insight-card`, etc.), apply those classes to `containerClass` rather than creating new components.
185
+ **Notes** — Use built-in props (`isTileCard`, `bgColorVariant`) or CSS layout classes (applied to `containerClass`) for variations like `item-card` or `insight-card`.
181
186
 
182
187
  ---
183
188
 
@@ -247,7 +252,9 @@ A thin wrapper around `AbModal` exposing imperative open/close.
247
252
  | `color` | String | `"primary"` | `success`, `danger`, `info`, `warning`, `primary`, `secondary`. |
248
253
  | `size` | String | `"md"` | `xs`, `sm`, `md`, `lg`, `xl`, `xxl`. |
249
254
 
250
- **Slots** ? `default` ? progress label (uses CSS custom property `--progress-value`).
255
+ **Slots** — `default` — progress label (uses CSS custom property `--progress-value`).
256
+
257
+ **Position Classes** — `progress-right`, `progress-right-top`, `progress-right-bottom`, `progress-value-top`, `progress-value-bottom`.
251
258
 
252
259
  ---
253
260
 
@@ -272,26 +279,12 @@ A thin wrapper around `AbModal` exposing imperative open/close.
272
279
  | `maxlength` | any | `null` | |
273
280
  | `isLeftIconBorder` | Boolean | `false` | |
274
281
  | `isRightIconBorder` | Boolean | `false` | |
275
- | Name | Type | Default | Notes |
276
- | ------------------- | --------------- | ---------- | ------------------------ |
277
- | `modelValue` | any | `null` | v-model binding. |
278
- | `label` | String | `""` | |
279
- | `placeholder` | String | `""` | |
280
- | `type` | String | `"text"` | Auto-detects `password`. |
281
- | `name` | String | _required_ | VeeValidate field name. |
282
- | `isCodeInput` | Boolean | `false` | |
283
- | `rules` | String / Object | `""` | VeeValidate rules. |
284
- | `containerClass` | String | `"mb-3"` | |
285
- | `hints` | String | `""` | |
286
- | `prefix` | String | `""` | |
287
- | `postfix` | String | `""` | |
288
- | `maxlength` | any | `null` | |
289
- | `isLeftIconBorder` | Boolean | `false` | |
290
- | `isRightIconBorder` | Boolean | `false` | |
282
+ | `isHideLabel` | Boolean | `false` | Hide the label visually. |
283
+ | `iconPosition` | String | `"right"` | Position of the custom `#icon` slot. |
291
284
 
292
285
  **Events** ? `update:modelValue`, `input`, `keyup`, `keydown`, `paste`.
293
286
 
294
- **Slots** ? `label`, `prefix`, `postfix`, `hints`.
287
+ **Slots** ? `label`, `prefix`, `postfix`, `icon`, `hints`.
295
288
 
296
289
  **v-model** ? yes.
297
290
 
@@ -368,10 +361,12 @@ Polymorphic field: renders text/number/textarea/select/multiselect/tag/checkbox/
368
361
  | `title` | String / null | `null` | Toggle/switch title. |
369
362
  | `isLeftIconBorder` | Boolean | `false` | |
370
363
  | `isRightIconBorder` | Boolean | `false` | |
364
+ | `isHideLabel` | Boolean | `false` | Hide the label visually. |
365
+ | `iconPosition` | String | `"right"` | Position of the custom `#icon` slot. |
371
366
 
372
367
  **Events** ? `update:modelValue`, `clear(event)`, `change(value)`, `select(value)`.
373
368
 
374
- **Slots** ? `label`, `prefix`, `postfix`, `description`, `helptext`, `option`, `singlelabel`.
369
+ **Slots** ? `label`, `prefix`, `postfix`, `icon`, `description`, `helptext`, `option`, `singlelabel`.
375
370
 
376
371
  **v-model** ? yes.
377
372
 
@@ -443,33 +438,9 @@ Dynamic form driven by a `fieldInputs` array where each entry declares `type` (`
443
438
  | `minuteStep` | Number | `1` | |
444
439
  | `isLeftIconBorder` | Boolean | `false` | |
445
440
  | `isRightIconBorder` | Boolean | `false` | |
446
- | Name | Type | Default | Notes |
447
- | --------------------------------------------- | --------------- | -------------- | ------------------------------------------------------------- |
448
- | `modelValue` | String / Object | `null` | For range mode, `{ start, end }`. |
449
- | `label` | String | `""` | |
450
- | `placeholder` | String | `""` | |
451
- | `name` | String | _required_ | |
452
- | `rules` | String / Object | `""` | |
453
- | `isRange` | Boolean | `false` | |
454
- | `containerClass` | String | `"mb-3"` | |
455
- | `hints` | String | `""` | |
456
- | `isDisable` | Boolean | `false` | |
457
- | `visibility` | String | `"click"` | |
458
- | `mask` | String | `""` | |
459
- | `dataFormat` | String | `"YYYY-MM-DD"` | |
460
- | `displayFormat` | String | `"YYYY-MM-DD"` | |
461
- | `maxDate` | Date / String | `undefined` | |
462
- | `minDate` | Date / String | `undefined` | |
463
- | `disableDates` | Array | `[]` | Accepts `Date`, string, or `{ repeat: { weekdays: [...] } }`. |
464
- | `showInInput` | Boolean | `true` | Input vs button trigger. |
465
- | `monthNames` / `monthNamesShort` / `dayNames` | Array | `undefined` | i18n overrides. |
466
- | `formatDigit` | Function | `undefined` | Locale digit formatter. |
467
- | `rangeSeparator` | String | `undefined` | |
468
- | `mode` | String | `"date"` | `date`, `time`, `datetime`. |
469
- | `is24Hour` | Boolean | `undefined` | |
470
- | `minuteStep` | Number | `1` | |
471
- | `isLeftIconBorder` | Boolean | `false` | |
472
- | `isRightIconBorder` | Boolean | `false` | |
441
+ | `isHideLabel` | Boolean | `false` | Hide the label visually. |
442
+ | `defaultIconPosition` | String | `"right"` | Position of the default calendar/clock icon. |
443
+ | `iconPosition` | String | `"right"` | Position of the custom `#icon` slot. |
473
444
 
474
445
  **Slots** ? `label`, `prefix`, `icon`, `hints`, `picker-container({ isRange, showInInput, value })`.
475
446
 
@@ -634,25 +605,12 @@ Option shape: `{ val, label?, img_src?, icon?, iconComponent?, icon_ctnr_class?,
634
605
  | `max` | Number | `0` | `0` = unlimited. |
635
606
  | `isLeftIconBorder` | Boolean | `false` | |
636
607
  | `isRightIconBorder` | Boolean | `false` | |
637
- | Name | Type | Default | Notes |
638
- | ------------------- | --------------- | ---------- | ----------------------------------- |
639
- | `modelValue` | Array | `[]` | |
640
- | `options` | Array | `[]` | Each: `{ val, title }` or a string. |
641
- | `label` | String | `""` | |
642
- | `placeholder` | String | `""` | |
643
- | `name` | String | _required_ | |
644
- | `rules` | String / Object | `""` | |
645
- | `containerClass` | String | `"mb-3"` | |
646
- | `hints` | String | `""` | |
647
- | `prefix` | String | `""` | |
648
- | `postfix` | String | `""` | |
649
- | `max` | Number | `0` | `0` = unlimited. |
650
- | `isLeftIconBorder` | Boolean | `false` | |
651
- | `isRightIconBorder` | Boolean | `false` | |
608
+ | `isHideLabel` | Boolean | `false` | Hide the label visually. |
609
+ | `iconPosition` | String | `"right"` | Position of the custom `#icon` slot. |
652
610
 
653
611
  **Events** ? `update:modelValue(array)`.
654
612
 
655
- **Slots** ? `label`, `prefix`, `postfix`, `hints`.
613
+ **Slots** ? `label`, `prefix`, `postfix`, `icon`, `hints`.
656
614
 
657
615
  **v-model** ? yes.
658
616
 
@@ -772,38 +730,12 @@ Custom built-in replacement for `@vueform/multiselect`.
772
730
  | `appendToBody` | Boolean | `true` | Teleport dropdown to `<body>`. |
773
731
  | `isLeftIconBorder` | Boolean | `false` | |
774
732
  | `isRightIconBorder` | Boolean | `false` | |
775
- | Name | Type | Default | Notes |
776
- | ------------------- | --------------- | ---------- | ------------------------------ |
777
- | `modelValue` | any | `null` | |
778
- | `label` | String | `""` | |
779
- | `placeholder` | String | `""` | |
780
- | `type` | String | `"text"` | |
781
- | `name` | String | _required_ | |
782
- | `rules` | String / Object | `""` | |
783
- | `containerClass` | String | `"mb-3"` | |
784
- | `hints` | String | `""` | |
785
- | `multiple` | Boolean | `false` | Deprecated ? use `mode`. |
786
- | `searchable` | Boolean | `false` | |
787
- | `mode` | String | `"single"` | `single`, `multiple`, `tags`. |
788
- | `options` | Array | `[]` | |
789
- | `labelKey` | String | `"title"` | |
790
- | `valueKey` | String | `"val"` | |
791
- | `max` | Number | `-1` | `-1` = unlimited. |
792
- | `object` | Boolean | `false` | Return full objects. |
793
- | `prefix` | String | `""` | |
794
- | `postfix` | String | `""` | |
795
- | `isAjaxSearch` | Boolean | `false` | |
796
- | `onSearch` | Function | `null` | AJAX search handler. |
797
- | `hideSelected` | Boolean | `true` | |
798
- | `loading` | Boolean | `false` | |
799
- | `disabled` | Boolean | `false` | |
800
- | `appendToBody` | Boolean | `true` | Teleport dropdown to `<body>`. |
801
- | `isLeftIconBorder` | Boolean | `false` | |
802
- | `isRightIconBorder` | Boolean | `false` | |
733
+ | `isHideLabel` | Boolean | `false` | Hide the label visually. |
734
+ | `iconPosition` | String | `"right"` | Position of the custom `#icon` slot. |
803
735
 
804
736
  **Events** ? `update:modelValue`, `clear`, `change(value)`, `select(value)`, `open`, `close`, `search-change(query)`.
805
737
 
806
- **Slots** ? `label`, `prefix`, `postfix`, `singlelabel(value)`, `option({ option, isSelected })`, `noresults`, `option-loading`, `loader-icon`.
738
+ **Slots** ? `label`, `prefix`, `postfix`, `icon`, `singlelabel(value)`, `option({ option, isSelected })`, `noresults`, `option-loading`, `loader-icon`.
807
739
 
808
740
  **v-model** ? yes.
809
741
 
@@ -1130,6 +1062,27 @@ No declared props. `AbKbd` renders a single `<kbd>`-like chip; `AbKbdGroup` comp
1130
1062
 
1131
1063
  ---
1132
1064
 
1065
+ ### AbChart
1066
+
1067
+ **Props**
1068
+
1069
+ | Name | Type | Default | Notes |
1070
+ | ------------ | ------ | ------------ | ------------------------------------------------------------------------------------------- |
1071
+ | `option` | Object | `{}` | Full ECharts option object. Overrides other props if provided. |
1072
+ | `chartType` | String | `""` | Simple chart type: `"line"`, `"bar"`, `"pie"`. |
1073
+ | `xAxisData` | Array | `[]` | Categories for the X-axis (used for line/bar). |
1074
+ | `seriesData` | Array | `[]` | Data points for the series. Use objects `{ value, name }` for Pie charts. |
1075
+ | `xAxisType` | String | `"category"` | X-axis scale type. |
1076
+ | `yAxisType` | String | `"value"` | Y-axis scale type. |
1077
+ | `legendOrient` | String | `""` | Orientation of the chart legend (e.g., `"vertical"`, `"horizontal"`). |
1078
+ | `showPointValues` | Boolean | `false` | If true, displays the value label on each data point in the chart. |
1079
+ | `height` | String | `"400px"` | Height of the chart container (e.g., "300px", "50%"). |
1080
+
1081
+
1082
+ **Slots** ? None.
1083
+
1084
+ ---
1085
+
1133
1086
  ## 4. Composables & Directives
1134
1087
 
1135
1088
  ### Directives
package/design-system.md ADDED
@@ -0,0 +1,403 @@
1
+ # Appsbd UI Library — Design System
2
+
3
+ **AI Assistant Instructions**:
4
+ This document is the **visual-language counterpart** to [AI_REFERENCE.md](./AI_REFERENCE.md). Where `AI_REFERENCE.md` documents component **APIs** (props, events, slots), this file documents the **design tokens** (colors, typography, spacing, radii, shadows, motion) that those components are built on. Use this file when you need to:
5
+
6
+ - Pick the right color, font size, radius, or spacing for new UI
7
+ - Style custom layouts that should feel consistent with built-in `Ab*` components
8
+ - Theme the library (light/dark, brand re-skinning)
9
+ - Translate a Figma mock from the Appsbd Design System to library code
10
+
11
+ **Source of truth.** The visual foundations below are derived from the **Appsbd Design System** folder (`./Appsbd Design System/`) — itself extracted from the **"Kigen design system"** Figma file. The library implements these tokens in SCSS using the `bb-` CSS-variable prefix and the `.apbd-` class prefix. Where a design-system token has a direct library variable, both names are listed.
12
+
13
+ ---
14
+
15
+ ## 1. Design Philosophy
16
+
17
+ The library follows four rules, in priority order:
18
+
19
+ 1. **Bootstrap variables first.** If a need can be met by overriding a Bootstrap CSS variable (e.g. `--bb-primary`, `--bb-border-radius`), do that.
20
+ 2. **Custom tokens second.** When Bootstrap has no matching variable (skeletons, sliders, custom panels), define a new token in `src/styles/_variables.scss` using the **`apbd-`** namespace under the **`bb-`** prefix, e.g. `--bb-apbd-bg-color`.
21
+ 3. **Class-variant over new component.** Layout variations of an existing base component (e.g. `tile-card`, `item-card`, `insight-card` for `AbCard`) are **CSS class extensions** in the corresponding `_component.scss`, not new SFCs.
22
+ 4. **Dark-mode safe colors.** Use `var(--bb-apbd-bg-color)` and `var(--bb-apbd-border-color)` inside component styles instead of `body-bg` or `border-color`, so light/dark switching just works.
23
+
24
+ > **Prefix rule.** CSS **class names** use `.apbd-` (e.g. `.apbd-skeleton`). CSS **variables** use `#{$prefix}` interpolation (e.g. `var(--#{$prefix}apbd-border-color)`, which compiles to `var(--bb-apbd-border-color)`).
25
+
26
+ ---
27
+
28
+ ## 2. Brand & Color System
29
+
30
+ ### 2.1 Primary brand color
31
+
32
+ The library's primary brand color is **Brand/600 — `#155EEF`** (Appsbd blue). It is the value of `--bb-primary` in the default (`blue`) skin and drives the focus ring, primary buttons, active nav, links, and component accents.
33
+
34
+ ### 2.2 Brand blue scale
35
+
36
+ Used for primary actions, links, focus rings, active states.
37
+
38
+ | Token | Hex | Library variable | Usage |
39
+ | ----------- | --------- | ------------------------- | ------------------------------ |
40
+ | Brand/25 | `#F5F8FF` | — | Very light tint |
41
+ | Brand/50 | `#EFF4FF` | `--bb-primary-light` | Active nav bg, light highlight |
42
+ | Brand/100 | `#D1E0FF` | — | Hover tint |
43
+ | Brand/200 | `#B2CCFF` | — | Border on blue tint |
44
+ | Brand/300 | `#84ADFF` | `--bb-apbd-border-color-focus` | Focus ring (light) |
45
+ | Brand/400 | `#528BFF` | — | Secondary interactive |
46
+ | Brand/500 | `#2970FF` | (dark-mode `--bb-primary`) | Hover on primary |
47
+ | **Brand/600** | **`#155EEF`** | **`--bb-primary` (light)** | **Primary action, brand blue** |
48
+ | Brand/700 | `#004EEB` | `--bb-primary-btn-hover` | Pressed / hover-darkened |
49
+ | Brand/800 | `#0040C1` | — | Dark brand |
50
+ | Brand/900 | `#00359E` | — | Very dark |
51
+ | Brand/950 | `#002266` | — | Darkest |
52
+
53
+ ### 2.3 Neutral / gray scale
54
+
55
+ Used for text, borders, surfaces, and dividers.
56
+
57
+ | Token | Hex | Usage |
58
+ | -------- | --------- | ------------------------------ |
59
+ | Gray/25 | `#FCFCFD` | Subtle backgrounds |
60
+ | Gray/50 | `#F9FAFB` | Table headers, inputs |
61
+ | Gray/100 | `#F2F4F7` | Light backgrounds, subtle border |
62
+ | Gray/200 | `#EAECF0` | Default dividers |
63
+ | Gray/300 | `#D0D5DD` | Borders |
64
+ | Gray/400 | `#98A2B3` | Disabled, placeholder |
65
+ | Gray/500 | `#667085` | Muted text |
66
+ | Gray/600 | `#475569` | Secondary text |
67
+ | Gray/700 | `#344054` | Body text |
68
+ | Gray/800 | `#1D2939` | Heading text |
69
+ | Gray/900 | `#101828` | Primary text |
70
+
71
+ ### 2.4 Semantic colors
72
+
73
+ Used by `AbBaseAlert`, `AbBadge`, `AbToast`, `AbButton variant`, form error states.
74
+
75
+ | Role | Background | Border | Text/Icon | Solid |
76
+ | ----------- | ---------- | --------- | --------- | --------- |
77
+ | **Success** | `#ECFDF3` | `#ABEFC6` | `#085D3A` | `#00C950` |
78
+ | **Error** | `#FEF2F2` | `#FECACA` | `#B91C1C` | `#FB2C36` |
79
+ | **Warning** | `#FFFBEB` | `#FDE68A` | `#92400E` | `#EEB004` |
80
+ | **Info** | `#EFF4FF` | `#B2CCFF` | `#155EEF` | `#2970FF` |
81
+
82
+ These map to Bootstrap's `--bb-success`, `--bb-danger`, `--bb-warning`, `--bb-info` variants used by `AbButton`'s `variant` prop and `AbBadge`'s `variant` prop.
83
+
84
+ ### 2.5 Surface & layout colors
85
+
86
+ | Role | Hex | Library variable |
87
+ | ------------------ | --------- | ------------------------------ |
88
+ | App shell bg | `#EBEFF5` | (page wrapper) |
89
+ | Card / panel | `#FFFFFF` | `--bb-apbd-bg-color` (light) |
90
+ | Sidebar bg | `#FFFFFF` | (`AbSidebar` root) |
91
+ | Topbar bg | `#FFFFFF` | |
92
+ | Table header bg | `#F9FAFB` | (`AbTable` thead) |
93
+ | Input bg | `#FFFFFF` | |
94
+ | Active nav-item bg | `#EFF4FF` | `--bb-apbd-sidebar-item-active-bg` |
95
+
96
+ > **Dark-mode rule.** Component styles must read from `var(--bb-apbd-bg-color)` / `var(--bb-apbd-border-color)` instead of hard-coding `#FFFFFF` / `#EAECF0`, so the values flip cleanly when `[data-bs-theme="dark"]` is set on the root.
97
+
98
+ ### 2.6 Borders
99
+
100
+ | Role | Hex | Library variable |
101
+ | -------------- | --------- | ------------------------------ |
102
+ | Default | `#EAECF0` | `--bb-apbd-border-color` |
103
+ | Strong | `#D5D7DA` | `--bb-apbd-border-color-strong` |
104
+ | Subtle | `#F2F4F7` | — |
105
+ | Brand / focus | `#155EEF` | `--bb-primary` |
106
+ | Focus ring | `#84ADFF` | `--bb-apbd-border-color-focus` |
107
+ | Error | `#FDA29B` | `--bb-apbd-input-error-border` |
108
+
109
+ ### 2.7 Theme skins
110
+
111
+ The library ships **multiple color skins** under `playground/skins/themes/`. Each is a `_<name>.scss` partial defining `$theme-color`, `$theme-color-light`, `$theme-color-dark`, `$theme-color-hover`, and `$border-color-focus-light`, then re-emitting them as `--bb-primary`, `--bb-primary-light`, `--bb-primary-rgb`, etc.
112
+
113
+ **Built-in skins:** `blue` (default), `black`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `violet`.
114
+
115
+ Skin switching is wired through the `AbColorPicker` in the playground; use the **`add-theme-skin`** project skill to add a new skin so all five wiring steps (theme partial, skin wrapper, vite rollup entry, picker option, `toggleTheme` mapping) are applied consistently.
116
+
117
+ ---
118
+
119
+ ## 3. Typography
120
+
121
+ ### 3.1 Font families
122
+
123
+ | Role | Family | Library token (CSS) | Usage |
124
+ | --------------- | ---------------- | ------------------- | ---------------------------------------- |
125
+ | **Sans (UI)** | **Inter** | `--font-sans` | All body, labels, headings, form fields |
126
+ | Nav | Geist | `--font-nav` | Sidebar nav items, app brand name |
127
+ | Display | Inter | `--font-display` | Hero / marketing display text |
128
+ | Auth headings | Inter Tight | `--font-auth` | Login / register screen titles |
129
+ | Mono | Geist | `--font-mono` | `<code>`, mono helpers |
130
+
131
+ `Inter` is the variable font shipped in `Appsbd Design System/fonts/`. `Geist` and `Inter Tight` come from Google Fonts.
132
+
133
+ ### 3.2 Display scale
134
+
135
+ For marketing pages, dashboards' hero numbers, and landing screens.
136
+
137
+ | Style | Size | Weight | Line height | Token |
138
+ | -------------- | ---- | ------ | ----------- | ------------------------------ |
139
+ | Display 2xl | 72px | 700 | 1.0 | `--text-display-2xl-*` |
140
+ | Display xl | 60px | 600 | 1.1 | `--text-display-xl-*` |
141
+ | Display lg | 48px | 600 | 1.1 | `--text-display-lg-*` |
142
+ | Display md | 44px | 600 | 1.15 | `--text-display-md-*` |
143
+ | Display sm | 30px | 600 | 1.2 | `--text-display-sm-*` |
144
+ | Display xs | 24px | 600 | 1.2 | `--text-display-xs-*` |
145
+
146
+ ### 3.3 Text scale
147
+
148
+ For app body, labels, captions.
149
+
150
+ | Style | Size | Weight | Line height | Library variable | Usage |
151
+ | -------- | ---- | ------ | ----------- | ------------------------------------ | ---------------------- |
152
+ | Text xl | 20px | 400 | 30px | `--bb-apbd-fs-lg` (1.5rem) | Large body, subheaders |
153
+ | Text lg | 18px | 400 | 28px | — | Subheadings |
154
+ | Text md | 16px | 400 | 24px | `--bb-apbd-fs-md` (1rem) | Body text (default) |
155
+ | Text sm | 14px | 400 | 20px | `--bb-apbd-fs-sm` (0.875rem) | Labels, nav, hints |
156
+ | Text xs | 12px | 400 | 16px | `--bb-apbd-fs-xs` (0.75rem) | Captions, meta |
157
+ | Text xxs | 11px | 400 | 14px | — | Micro labels |
158
+
159
+ ### 3.4 Font weights
160
+
161
+ | Token | Weight | Library variable |
162
+ | ------ | ------ | ----------------------------- |
163
+ | Thin | 300 | `--bb-apbd-fw-thin` |
164
+ | Normal | 400 | `--bb-apbd-fw-normal` |
165
+ | Bold | 500 | `--bb-apbd-fw-bold` (medium) |
166
+ | Bolder | 600 | `--bb-apbd-fw-bolder` (semi) |
167
+ | Boldest| 700 | `--bb-apbd-fw-boldest` |
168
+
169
+ ### 3.5 Semantic type helpers
170
+
171
+ These class names exist in `Appsbd Design System/colors_and_type.css` as a cheat-sheet for ad-hoc HTML; library components apply equivalent styles internally.
172
+
173
+ - `.h1` — 24/32 medium, primary text
174
+ - `.h2` — 20/28 semibold, primary text
175
+ - `.h3` — 16/24 bold, primary text
176
+ - `.body` — 16/24 regular, secondary text
177
+ - `.label` — 14/20 medium, primary text
178
+ - `.caption` — 12/16 regular, muted text
179
+ - `.nav-label` / `.nav-label--active` — 16/24 Geist
180
+ - `.auth-heading` — 22/28 Inter Tight medium
181
+
182
+ ### 3.6 Tone & voice
183
+
184
+ When generating copy for screens built with this library:
185
+
186
+ - **Professional but approachable** — direct, benefit-led. Not overly casual.
187
+ - **Second person ("you")** — e.g. "Welcome back, Sarah."
188
+ - **Action-oriented labels** — "Add Application", "Renew", "Sign out".
189
+ - **Sentence case for body UI**, **Title Case for nav labels**.
190
+ - **No emoji in production UI copy.**
191
+ - **Numbers used sparingly and cleanly** — `7`, `$13,710`, `2`.
192
+
193
+ ---
194
+
195
+ ## 4. Spacing & Layout
196
+
197
+ ### 4.1 Spacing scale (4px base)
198
+
199
+ | Token | Value | CSS var |
200
+ | -------------- | ----- | ---------------- |
201
+ | `--space-1` | 4px | |
202
+ | `--space-2` | 8px | |
203
+ | `--space-2-5` | 10px | |
204
+ | `--space-3` | 12px | |
205
+ | `--space-4` | 16px | |
206
+ | `--space-5` | 20px | |
207
+ | `--space-6` | 24px | |
208
+ | `--space-8` | 32px | |
209
+ | `--space-10` | 40px | |
210
+ | `--space-12` | 48px | |
211
+ | `--space-16` | 64px | |
212
+
213
+ Common gaps: **4, 8, 12, 16, 24, 32, 48, 64**.
214
+
215
+ ### 4.2 App layout
216
+
217
+ | Region | Size | Note |
218
+ | ---------------- | ----------------- | ------------------------------------------------------- |
219
+ | Sidebar width | **256px** fixed | `AbSidebar` collapsed state managed via provide/inject |
220
+ | Topbar height | **80px** | |
221
+ | Content padding | **24px** | `--bb-apbd-container-page-padding` (≈ 0.937rem default) |
222
+ | Card padding | **24–32px** | `--bb-apbd-card-*` variables |
223
+
224
+ ### 4.3 Component sizing scale
225
+
226
+ Many components expose a `size` prop with values **`xs`, `sm`, `md`, `lg`, `xl`, `xxl`** (default `md`). The size is mapped to per-component padding/font tokens in `_variables.scss` (e.g. `--bb-input-field-padding-md`, `--bb-apbd-btn-padding-md-x`). Pick:
227
+
228
+ - `xs` / `sm` — dense forms, table inline editors, filter panels
229
+ - `md` — default app content, settings forms, modals
230
+ - `lg` / `xl` — auth screens, wizard steps, marketing surfaces
231
+ - `xxl` — display / hero CTAs
232
+
233
+ ---
234
+
235
+ ## 5. Corner Radii
236
+
237
+ | Token | Value | Library variable | Usage |
238
+ | ------------- | ------ | ------------------------- | -------------------------------- |
239
+ | `--radius-xs` | 4px | — | Tags, small pills |
240
+ | `--radius-sm` | 6px | `--bb-border-radius-sm` | Small buttons |
241
+ | `--radius-md` | 8px | `--bb-border-radius` | Inputs, buttons (sm/md) |
242
+ | `--radius-lg` | 10px | `--bb-border-radius-lg` | Nav items, buttons (lg/xl) |
243
+ | `--radius-xl` | 12px | — | Search bar, medium cards |
244
+ | `--radius-2xl`| 14px | — | Icon containers |
245
+ | `--radius-3xl`| 16px | `--bb-apbd-card-border-radius` (≈ 0.875rem) | Cards |
246
+ | `--radius-pill` | 9999px | — | Badges, avatars (`AbAvatar`) |
247
+
248
+ ---
249
+
250
+ ## 6. Shadows & Elevation
251
+
252
+ Flat by default. Shadows are reserved for cards, dropdowns, popovers, and elevated modals.
253
+
254
+ | Token | Value | Usage |
255
+ | ---------------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
256
+ | `--shadow-xs` | `0px 1px 2px 0px rgba(16,24,40,0.05)` | Subtle resting elevation |
257
+ | `--shadow-sm` | `0px 1px 2px -1px rgba(0,0,0,0.1), 0px 1px 3px 0px rgba(0,0,0,0.1)` | Cards (default `AbCard`) |
258
+ | `--shadow-md` | `0px 2px 4px -2px rgba(16,24,40,0.06), 0px 4px 8px -2px rgba(16,24,40,0.10)` | Dropdowns, popovers (`AbPopover`) |
259
+ | `--shadow-lg` | `0px 4px 6px -2px rgba(16,24,40,0.03), 0px 12px 16px -4px rgba(16,24,40,0.08)` | Modals (`AbModal`, `AbEasyModal`) |
260
+ | `--shadow-card` | `0px 2px 2px 0px rgba(0,0,0,0.03)` | Soft card variant |
261
+
262
+ **No gradients on UI surfaces.** Gradients appear only in design documentation headers, never in app chrome.
263
+
264
+ ---
265
+
266
+ ## 7. Iconography
267
+
268
+ **Library: [Lucide Icons](https://lucide.dev/)** — installed as the `lucide-vue-next` peer dependency. Bootstrap Icons is also a peer dep and may be used for a few legacy components.
269
+
270
+ ### Sizing
271
+
272
+ | Size | Usage |
273
+ | ----- | ------------------------------------------- |
274
+ | 16×16 | Inline / topbar buttons / dense controls |
275
+ | 20×20 | Nav items (default), most `AbButton` icons |
276
+ | 24×24 | Larger nav, prominent actions, empty states |
277
+
278
+ - **Stroke weight:** 1.5–2px (Lucide default).
279
+ - **Color:** inherits text color; active nav/icons = `--bb-primary` (`#155EEF`); muted = `#717680`.
280
+
281
+ ### Common icons in use
282
+
283
+ `panel-right-open`, `plus`, `arrow-up`, `arrow-right`, `chevron-left`, `chevron-down`, `sparkles`, `house`, `log-out`, `alert-circle`, `x`, `user`, `refresh-ccw`, `mail`, `search`.
284
+
285
+ **Rules:** All icons are SVG via Lucide. **No emoji in production UI.** No PNG icons. No custom icon font.
286
+
287
+ ---
288
+
289
+ ## 8. Interaction & Motion
290
+
291
+ ### 8.1 Hover / focus / pressed
292
+
293
+ | State | Treatment |
294
+ | ---------------------- | -------------------------------------------------------------------------- |
295
+ | Primary button hover | Darken to Brand/700 `#004EEB` (`--bb-primary-btn-hover`) |
296
+ | Nav item hover | Light blue tint `#EFF4FF` background |
297
+ | Card hover | Static — no shadow animation by default |
298
+ | Link | Brand/600 `#155EEF`; underline on hover |
299
+ | Input focus | Border `#155EEF`; subtle focus ring `--bb-apbd-input-box-shadow` |
300
+ | Form check / toggle on | `--bb-apbd-checkbox-checked-form-check-bg` / `--bb-apbd-toggle-checked-bg` |
301
+
302
+ ### 8.2 Motion principles
303
+
304
+ - **Minimal animation.** No bounces or springs.
305
+ - **Implied CSS ease** (no overrides). Treat `transition: 150–200ms ease` as default.
306
+ - **Sidebar collapse** — toggled via `panel-right-open` icon; uses CSS width transition.
307
+
308
+ ---
309
+
310
+ ## 9. Dark mode
311
+
312
+ Dark mode is opt-in via `[data-bs-theme="dark"]` on the root and managed by the **`useTheme`** composable + **`AbDarkModeToggler`** component (see [AI_REFERENCE.md §4](./AI_REFERENCE.md#4-composables--directives)).
313
+
314
+ Each theme partial in `playground/skins/themes/_<name>.scss` re-emits brand variables for dark mode. Authors of new components must:
315
+
316
+ - Use `var(--bb-apbd-bg-color)` and `var(--bb-apbd-border-color)` for surfaces and dividers.
317
+ - Avoid hard-coded `#FFFFFF` / `#EAECF0` etc.
318
+ - Test both light and dark in the playground before shipping.
319
+
320
+ ---
321
+
322
+ ## 10. Component → Token Map
323
+
324
+ How design tokens land in built-in components. Use this when generating layouts so the look stays consistent. For full component APIs, follow each link to [AI_REFERENCE.md](./AI_REFERENCE.md).
325
+
326
+ | Component | Primary tokens |
327
+ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
328
+ | [`AbButton`](./AI_REFERENCE.md#abbutton) | `--bb-primary`, `--bb-primary-btn-hover`, radii via `--bb-border-radius` / `-lg`, `--bb-apbd-btn-padding-*` |
329
+ | [`AbCard`](./AI_REFERENCE.md#abcard) | `--bb-apbd-card-border-radius` (`16px`), `--shadow-sm`, surface white, border `#D5D7DA` |
330
+ | [`AbModal`](./AI_REFERENCE.md#abmodal) / [`AbEasyModal`](./AI_REFERENCE.md#abeasymodal) | `--bb-apbd-modal-*` paddings, backdrop `rgba(0,0,0,0.7)` (`--bb-apbd-modal-bg-opacity`), `--shadow-lg` |
331
+ | [`AbInputField`](./AI_REFERENCE.md#abinputfield) / [`AbNumberField`](./AI_REFERENCE.md#abnumberfield) / [`AbMultiSelect`](./AI_REFERENCE.md#abmultiselect) | `--bb-input-field-padding-*`, `--bb-apbd-border-color-focus`, `--bb-apbd-input-box-shadow` |
332
+ | [`AbBadge`](./AI_REFERENCE.md#abbadge) | Semantic palette (success / error / warning / info), pill radius `9999px` |
333
+ | [`AbAvatar`](./AI_REFERENCE.md#abavatar) | `--radius-pill`, sizing scale `xs–xxl` |
334
+ | [`AbSidebar`](./AI_REFERENCE.md#absidebar) / [`AbSideMenuItem`](./AI_REFERENCE.md#absidemenuitem) | width `256px`, active bg `#EFF4FF`, active text `--bb-primary`, font `--font-nav` (Geist) |
335
+ | [`AbProgressbar`](./AI_REFERENCE.md#abprogressbar) | `--bb-apbd-progressbar-fill-bg-primary`, semantic color variants |
336
+ | [`AbSlider`](./AI_REFERENCE.md#abslider) | `--bb-apbd-slider-fill-bg`, `--bb-apbd-slider-thumb-border-color`, `--bb-apbd-slider-thumb-focus-shadow` |
337
+ | [`AbToggle`](./AI_REFERENCE.md#abtoggle) / [`AbFormCheck`](./AI_REFERENCE.md#abformcheck--abradioinput) | `--bb-apbd-toggle-checked-bg`, `--bb-apbd-checkbox-checked-form-check-bg` |
338
+ | [`AbToast`](./AI_REFERENCE.md#abtoast) (via `useToast`) | Semantic palette, `--shadow-md` |
339
+ | [`AbTable`](./AI_REFERENCE.md#abtable) | Header bg `#F9FAFB`, divider `--bb-apbd-border-color` |
340
+ | [`AbDarkModeToggler`](./AI_REFERENCE.md#abdarkmodetoggler) | Pairs with `useTheme`; flips `[data-bs-theme]` on root |
341
+
342
+ ---
343
+
344
+ ## 11. Implementation Notes
345
+
346
+ ### 11.1 SCSS structure
347
+
348
+ ```
349
+ src/styles/
350
+ ├── index.scss # Main entry; wraps imports in .#{$app_class}
351
+ ├── _prefix.scss # $prefix: "bb-" / $app_class: "appsbd-app"
352
+ ├── _variables.scss # All --bb-apbd-* design tokens
353
+ ├── _mixins.scss
354
+ ├── components/ # Per-component partials (do NOT wrap in .#{$app_class})
355
+ │ ├── _button.scss
356
+ │ ├── _card.scss
357
+ │ └── ...
358
+ └── rtl/ # RTL-specific overrides
359
+ ```
360
+
361
+ When editing any `.scss` under `src/styles/`, invoke the **`scss-conventions`** project skill — it encodes the prefix-vs-class rule, the no-double-nesting rule for component partials, and the dark-mode tokens.
362
+
363
+ ### 11.2 Adding a new design token
364
+
365
+ 1. Decide whether Bootstrap already has a variable for it. If yes, override there.
366
+ 2. Otherwise, add it to `src/styles/_variables.scss` under the `apbd-` namespace: `--#{$prefix}apbd-<component>-<property>`.
367
+ 3. Use the new token in component partials via `var(--#{$prefix}apbd-...)`.
368
+ 4. If the token participates in theming, add a corresponding line to each `playground/skins/themes/_<color>.scss` partial.
369
+
370
+ ### 11.3 Adding a new color skin
371
+
372
+ Use the **`add-theme-skin`** project skill — it wires the 5 places a new skin must touch:
373
+
374
+ 1. `playground/skins/themes/_<name>.scss` (defines `$theme-color`, `$theme-color-light`, `$theme-color-dark`, `$theme-color-hover`, `$border-color-focus-light`)
375
+ 2. `playground/skins/<name>.scss` (skin wrapper)
376
+ 3. `vite.config.js` rollup input + `assetFileNames` allow-list
377
+ 4. `AbColorPicker` option in the playground
378
+ 5. `toggleTheme` name → CSS mapping
379
+
380
+ ### 11.4 Adding a new component
381
+
382
+ Use the **`add-ab-component`** project skill — it walks the 9-step wiring (SFC + barrel export, SCSS partial + correct import location, playground docs page, router entry, sidebar menu item, `ComponentsOverview` entry, AI reference files).
383
+
384
+ ### 11.5 Updating tokens or component APIs
385
+
386
+ Whenever a component's public API or visual tokens change, update **all four** of:
387
+
388
+ 1. The component's playground `*Test.vue` (use the **`write-component-docs`** skill).
389
+ 2. [AI_REFERENCE.md](./AI_REFERENCE.md) (component table row + section-3 API block).
390
+ 3. `.ai/ai_ref_<ComponentName>.md`.
391
+ 4. This file (**`design-system.md`**) if the change adds/renames a public design token.
392
+
393
+ The **`update-ai-reference`** project skill enforces (2) and (3).
394
+
395
+ ---
396
+
397
+ ## 12. Source materials
398
+
399
+ - **`Appsbd Design System/README.md`** — design system narrative (foundations, tone, iconography).
400
+ - **`Appsbd Design System/colors_and_type.css`** — CSS-variable form of every token below; copy-paste-ready.
401
+ - **`Appsbd Design System/preview/*.html`** — visual specimens for colors, type, spacing, shadows, buttons, badges, inputs, nav, cards, avatars, tabs.
402
+ - **`Appsbd Design System/ui_kits/system-admin/`** — interactive prototype (Dashboard, Tickets, Auth) that exercises every token in context.
403
+ - **`AI_REFERENCE.md`** — component API reference; the "what props/events/slots" companion to this "what colors/sizes/spacings" document.