From f8ab4aed00a42457173f21f61679193c8c0e71a0 Mon Sep 17 00:00:00 2001 From: John Traas Date: Fri, 20 Mar 2026 16:05:46 +0100 Subject: [PATCH 1/2] feat(plugin): add lime-elements-toolkit Claude Code plugin (alpha) Installable plugin that helps developers consume lime-elements to build UIs. Bundles distilled design system knowledge and component guidance as self-contained reference docs, with four auto-triggering skills: - build: scaffold UIs with correct design system conventions - component-guide: look up components, props, and usage patterns - design-review: audit code against color, sizing, shadow, and interaction pattern rules - accessibility: WCAG 2.1 AA audit with lime-elements-specific checks References cover ~50 public components, the full color system, 4x sizing rhythm, shadow variables, declutter philosophy, and interaction patterns (switch vs checkbox, disabled vs readonly, action buttons). Co-Authored-By: Claude Opus 4.6 (1M context) --- plugin/.claude-plugin/plugin.json | 15 + plugin/LICENSE | 191 ++++++++++ plugin/README.md | 53 +++ plugin/references/component-catalog.md | 411 ++++++++++++++++++++++ plugin/references/design-system.md | 181 ++++++++++ plugin/references/interaction-patterns.md | 119 +++++++ plugin/skills/accessibility/SKILL.md | 107 ++++++ plugin/skills/build/SKILL.md | 44 +++ plugin/skills/component-guide/SKILL.md | 61 ++++ plugin/skills/design-review/SKILL.md | 71 ++++ 10 files changed, 1253 insertions(+) create mode 100644 plugin/.claude-plugin/plugin.json create mode 100644 plugin/LICENSE create mode 100644 plugin/README.md create mode 100644 plugin/references/component-catalog.md create mode 100644 plugin/references/design-system.md create mode 100644 plugin/references/interaction-patterns.md create mode 100644 plugin/skills/accessibility/SKILL.md create mode 100644 plugin/skills/build/SKILL.md create mode 100644 plugin/skills/component-guide/SKILL.md create mode 100644 plugin/skills/design-review/SKILL.md diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000000..4d2b4e1b57 --- /dev/null +++ b/plugin/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "lime-elements-toolkit", + "description": "Build UIs with lime-elements — design system knowledge, component guidance, design reviews, and accessibility audits for the @limetech/lime-elements web component library.", + "author": "Lime Technologies", + "keywords": [ + "lime-elements", + "web-components", + "stencil", + "design-system", + "ui", + "components", + "accessibility" + ], + "version": "0.1.0-alpha" +} diff --git a/plugin/LICENSE b/plugin/LICENSE new file mode 100644 index 0000000000..88c9110c28 --- /dev/null +++ b/plugin/LICENSE @@ -0,0 +1,191 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by the Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding any notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2024 Lime Technologies + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/plugin/README.md b/plugin/README.md new file mode 100644 index 0000000000..135644744f --- /dev/null +++ b/plugin/README.md @@ -0,0 +1,53 @@ +# lime-elements-toolkit + +A Claude Code plugin that helps developers build UIs with `@limetech/lime-elements`. It bundles the lime-elements design system knowledge, component guidance, and best practices — so Claude can help you write code that follows the design system correctly. + +## Installation + +```bash +# From the lime-elements repo +claude --plugin-dir ./plugin + +# Or install from a path +claude plugin install ./plugin +``` + +## Skills + +### Build UI (`build`) +Build user interfaces using lime-elements components, with the design system's color, sizing, shadow, and interaction conventions applied automatically. + +**Triggers on:** "build a form", "create a dialog", "implement a page with lime-elements", "make a UI for..." + +### Component Guide (`component-guide`) +Look up how to use a specific component, find the right component for a use case, or get usage examples with correct event handling and slot patterns. + +**Triggers on:** "how do I use limel-button", "what component for a toggle", "show me how to use the picker" + +### Design Review (`design-review`) +Review existing UI code for compliance with the lime-elements design system — colors, sizing, shadows, interaction patterns, and declutter principles. + +**Triggers on:** "review my UI code", "check my design", "does this follow the design system" + +### Accessibility Audit (`accessibility`) +Audit UI code for WCAG 2.1 AA compliance, plus lime-elements-specific patterns like disabled vs readonly, hidden vs disabled, and boolean field labeling. + +**Triggers on:** "check accessibility", "a11y audit", "WCAG compliance check" + +## Reference Docs + +The plugin bundles distilled design system knowledge in `references/`: + +- **`design-system.md`** — Color system (palettes, CSS variables, dark mode, accent color), size rhythms (4x rule, rem units), shadows (button/surface/state variables), declutter philosophy +- **`component-catalog.md`** — All ~50 public components with tag names, key props, and use cases +- **`interaction-patterns.md`** — Switch vs checkbox, disabled vs readonly, hidden vs disabled, action button placement and labeling + +## What This Plugin Does NOT Do + +- It does not replace reading the [full documentation](https://lundalogik.github.io/lime-elements/) +- It does not cover lime-elements internals or contribution guidelines +- It does not include every prop/event — consult component readmes for exhaustive API docs + +## License + +Apache-2.0 (same as lime-elements) diff --git a/plugin/references/component-catalog.md b/plugin/references/component-catalog.md new file mode 100644 index 0000000000..4fec777cd1 --- /dev/null +++ b/plugin/references/component-catalog.md @@ -0,0 +1,411 @@ +# lime-elements Component Catalog + +All components use the `limel-` tag prefix. They are Web Components (shadow DOM) built with Stencil.js and work with any framework. + +**Package:** `@limetech/lime-elements` +**Docs:** https://lundalogik.github.io/lime-elements/ + +--- + +## Navigation & Layout + +### `limel-dock` +Vertical navigation sidebar with icons, labels, badges, and collapsible state. Switches to horizontal on mobile. + +**Key props:** `dockItems`, `dockFooterItems`, `expanded`, `allowResize`, `mobileBreakPoint` +**Use cases:** Primary app navigation. Supports nested popover menus and badge counts. + +### `limel-tab-bar` +Horizontal scrollable tabs for switching between content sections. + +**Key props:** `tabs` +**Use cases:** Top-level content organization. Supports icons and badges. Never nest tab bars. + +### `limel-tab-panel` +Combines tab bar with slotted content panels — auto-shows the active panel. + +**Key props:** `tabs` +**Use cases:** Convenience wrapper when each tab maps to a slotted element. + +### `limel-breadcrumbs` +Horizontal navigation trail showing hierarchy or history. + +**Key props:** `items`, `divider` +**Use cases:** Page hierarchy navigation. Items can be links or buttons. + +### `limel-shortcut` +A navigational tile with icon and label for dashboards and start pages. + +**Key props:** `icon`, `label`, `link`, `badge`, `disabled` +**Use cases:** Quick-access navigation tiles on home screens. + +### `limel-grid` +CSS Grid wrapper for responsive layouts. + +**Key props:** (CSS-driven) +**Use cases:** Responsive page layouts and card grids. + +### `limel-flex-container` +Flexbox layout wrapper. + +**Key props:** (CSS-driven) +**Use cases:** Horizontal/vertical arrangements of child elements. + +--- + +## Buttons & Actions + +### `limel-button` +Standard clickable button for triggering actions. + +**Key props:** `label`, `icon`, `primary`, `outlined`, `disabled`, `loading`, `loadingFailed` +**Use cases:** Form submission, dialogs, commands. Use `primary` for the main action. + +### `limel-icon-button` +Icon-only button with accessible label shown to screen readers/tooltip. + +**Key props:** `icon`, `label`, `disabled`, `elevated` +**Use cases:** Toolbar actions, header controls, compact UI. `elevated` adds shadow. + +### `limel-split-button` +Button with primary action + dropdown arrow revealing alternatives. + +**Key props:** `label`, `icon`, `items`, `primary`, `disabled`, `loading` +**Use cases:** "Save" with "Save and close" / "Save as draft" alternatives. + +### `limel-button-group` +Set of mutually selectable buttons for view switching or filtering. + +**Key props:** `value`, `disabled` +**Use cases:** Toggle between views (Map/Satellite) or quick filters. + +### `limel-action-bar` +Centralized hub for context-relevant actions, supports floating layout. + +**Key props:** `actions`, `collapsible`, `layout`, `openDirection` +**Use cases:** Toolbars, bulk operation bars, floating action panels. + +--- + +## Form Inputs + +### `limel-input-field` +Versatile text input: text, number, email, URL, phone, password, search, textarea. + +**Key props:** `value`, `type`, `label`, `disabled`, `readonly`, `required`, `invalid`, `helperText`, `leadingIcon`, `trailingIcon`, `prefix`, `suffix`, `completions`, `maxlength`, `pattern` +**Use cases:** Any free-text or numeric input in a form. Supports inline autocomplete. + +### `limel-select` +Styled dropdown for choosing from a fixed list. + +**Key props:** `options`, `value`, `label`, `multiple`, `disabled`, `readonly`, `required` +**Use cases:** When options are enumerable and fixed (unlike picker's dynamic search). + +### `limel-picker` +Search-as-you-type field for finding and selecting items, shown as chips. + +**Key props:** `value`, `label`, `searcher`, `allItems`, `multiple`, `disabled`, `readonly`, `required` +**Use cases:** Associating records (contacts, users, tags) from large datasets. Provide `searcher` for server-side lookup. + +### `limel-checkbox` +Classic checkbox with checked, unchecked, and indeterminate states. + +**Key props:** `checked`, `label`, `disabled`, `readonly`, `indeterminate`, `required` +**Use cases:** Multi-selection in forms and settings. Indeterminate for parent checkboxes. + +### `limel-switch` +Binary toggle for immediate-effect settings. + +**Key props:** `value`, `label`, `disabled`, `readonly`, `required` +**Use cases:** Settings that take effect immediately (dark mode, notifications). Use checkbox when submit is needed. + +### `limel-radio-button-group` +Mutually exclusive radio buttons from a list of items. + +**Key props:** `items`, `selectedItem`, `disabled` +**Use cases:** Exactly one option from a short list. Always provide 2+ options. + +### `limel-slider` +Range input for numeric value selection. + +**Key props:** `value`, `label`, `valuemin`, `valuemax`, `step`, `unit`, `disabled`, `readonly` +**Use cases:** Numeric ranges in settings or filters (percentages, temperatures). + +### `limel-date-picker` +Date/time input with calendar popover (Flatpickr). + +**Key props:** `value`, `type`, `label`, `disabled`, `readonly`, `required`, `language`, `format` +**Use cases:** Date, time, datetime, week, month, quarter, year selection. + +### `limel-color-picker` +Color selection from design-system swatches with optional manual hex input. + +**Key props:** `value`, `label`, `disabled`, `readonly`, `required`, `manualInput`, `palette` +**Use cases:** Assigning colors to categories, tags, or themes. + +### `limel-file` +Single-file picker displayed as a chip. + +**Key props:** `value`, `label`, `accept`, `disabled`, `readonly`, `required` +**Use cases:** Attaching a single file in a form. + +### `limel-file-input` +Wraps any element to open native file chooser on click. + +**Key props:** `accept`, `disabled`, `multiple` +**Use cases:** Turning a custom button into a file selector. + +### `limel-file-dropzone` +Converts a UI region into a drag-and-drop upload target. + +**Key props:** `accept`, `disabled`, `text`, `helperText` +**Use cases:** Drag-and-drop file upload areas. + +### `limel-profile-picture` +Circular avatar with image upload support and optional client-side resizing. + +**Key props:** `value`, `label`, `icon`, `disabled`, `readonly`, `resize` +**Use cases:** User profile forms and contact cards. + +### `limel-form` +JSON-Schema-driven form renderer with automatic validation. + +**Key props:** `schema`, `value`, `disabled`, `errors`, `propsFactory` +**Use cases:** Rapidly render validated forms from JSON Schema without manual field composition. + +### `limel-text-editor` +Rich text editor (ProseMirror) with markdown/HTML support and formatting toolbar. + +**Key props:** `value`, `label`, `contentType`, `ui`, `disabled`, `readonly`, `required`, `triggers`, `customElements` +**Use cases:** Long-form text input (notes, comments). Supports `@`-mentions via triggers. + +### `limel-code-editor` +Code editing field (CodeMirror) with syntax highlighting and linting. + +**Key props:** `value`, `language`, `label`, `disabled`, `readonly`, `lineNumbers`, `lineWrapping`, `lint` +**Use cases:** Editing JSON, JavaScript, HTML, CSS, or other code in forms/settings. + +--- + +## Data Display + +### `limel-list` +Flexible list with plain, selectable, radio, and checkbox modes. + +**Key props:** `items`, `type`, `badgeIcons`, `iconSize` +**Use cases:** Collections with optional selection. `type="selectable"` for single, `type="checkbox"` for multi. + +### `limel-table` +Full-featured data table with sorting, pagination, selection, and custom cells. + +**Key props:** `data`, `columns`, `loading`, `mode`, `selectable`, `sorting`, `pageSize`, `totalRows` +**Use cases:** Tabular data display. `mode="remote"` for server-side paging/sorting. + +### `limel-chart` +Data visualization: bar, line, area, pie, doughnut, ring, dot, stacked-bar, NPS. + +**Key props:** `items`, `type`, `orientation`, `maxValue`, `loading` +**Use cases:** Dashboard charts and reports. + +### `limel-info-tile` +Dashboard metric tile with label, value, badge, and optional progress ring. + +**Key props:** `value`, `label`, `icon`, `badge`, `link`, `loading`, `progress` +**Use cases:** Key metrics on start pages and dashboards. + +### `limel-circular-progress` +Compact circular progress indicator. + +**Key props:** `value`, `maxValue`, `suffix`, `size` +**Use cases:** Completion percentages and scored metrics in constrained spaces. + +### `limel-linear-progress` +Horizontal progress bar (determinate or indeterminate). + +**Key props:** `value`, `indeterminate` +**Use cases:** Task completion or ongoing process indication. + +### `limel-progress-flow` +Horizontal stepper showing named workflow steps. + +**Key props:** `flowItems`, `disabled`, `readonly` +**Use cases:** Sales pipeline stages, ticket statuses, wizard steps. + +### `limel-code-diff` +Visual diff between two text values (GitHub-style). + +**Key props:** `oldValue`, `newValue`, `layout`, `language`, `contextLines` +**Use cases:** Before/after comparison of text or JSON. Supports unified and split views. + +### `limel-markdown` +Renders GitHub Flavored Markdown as formatted HTML. + +**Key props:** `value`, `whitelist`, `lazyLoadImages` +**Use cases:** Rich text display from markdown strings (help, comments, descriptions). + +### `limel-icon` +Renders an icon from the configured icon set. + +**Key props:** `name`, `size`, `badge` +**Use cases:** Icons throughout the UI. Sizes: `x-small`, `small`, `medium`, `large`. + +### `limel-badge` +Small notification badge with optional numeric/text label. + +**Key props:** `label` +**Use cases:** Notification counts on icons, tabs, dock items. + +--- + +## Containers & Surfaces + +### `limel-dialog` +Modal overlay for focused interactions. + +**Key props:** `open`, `heading`, `fullscreen`, `closingActions` +**Use cases:** Confirmations, forms, complex interactions. Slots: default, `button`, header actions. + +### `limel-popover` +Non-modal floating layer anchored to a trigger element. + +**Key props:** `open`, `openDirection` +**Use cases:** Contextual options, rich content overlays. Dismisses on outside click. + +### `limel-card` +Structured content container with header, media, body, and actions. + +**Key props:** `heading`, `subheading`, `icon`, `image`, `actions`, `clickable`, `selected`, `orientation` +**Use cases:** Dashboard items, record previews. Portrait or landscape orientation. + +### `limel-collapsible-section` +Toggleable section with header. + +**Key props:** `header`, `isOpen`, `icon`, `invalid`, `actions` +**Use cases:** Grouping form fields or content that can be collapsed. + +### `limel-header` +Top structural element of a card/modal/view with icon, title, and actions. + +**Key props:** `heading`, `icon`, `subheading`, `supportingText` +**Use cases:** Top of cards, dialogs, views. Slot in actions via `"actions"` slot. + +--- + +## Feedback & Messaging + +### `limel-snackbar` +Transient toast notification at the bottom of screen. + +**Key props:** `message`, `open`, `timeout`, `dismissible`, `actionText` +**Use cases:** Brief feedback (saved, uploaded, failed). `timeout=-1` for persistent. + +### `limel-banner` +Persistent message bar at the top of a section. + +**Key props:** `message`, `icon` +**Use cases:** Important messages requiring user acknowledgment (outage warnings, required actions). + +### `limel-callout` +Highlighted admonition block. + +**Key props:** `type`, `heading`, `icon` +**Use cases:** Note, tip, warning, caution, or important callouts in text/forms. + +### `limel-spinner` +Loading activity indicator. + +**Key props:** `size`, `limeBranded` +**Use cases:** Loading states. `limeBranded` for Lime logo spinner. + +### `limel-tooltip` +Descriptive text tooltip shown on hover. + +**Key props:** `elementId`, `label`, `helperLabel`, `openDirection` +**Use cases:** Supplemental hints on icon buttons and compact elements. + +### `limel-help` +Contextual help button opening a markdown popover. + +**Key props:** `value`, `readMoreLink`, `openDirection` +**Use cases:** Inline help for form fields or complex UI sections. + +--- + +## Chips & Tags + +### `limel-chip` +Compact interactive element representing a choice, filter, tag, or item. + +**Key props:** `text`, `icon`, `badge`, `selected`, `removable`, `disabled`, `readonly`, `type`, `link` +**Use cases:** Tags, filters, selected entities. Use `removable` for deletion, `link` for navigation. + +### `limel-chip-set` +Managed collection of chips: choice (single), filter (multi), input (text entry). + +**Key props:** `value`, `type`, `label`, `disabled`, `readonly`, `required`, `multiple`, `maxItems`, `delimiter` +**Use cases:** `type="input"` for tag entry, `type="choice"` for exclusive selection, `type="filter"` for multi-select. + +--- + +## Menus + +### `limel-menu` +Dropdown context menu with sub-menus, search, and grid layout. + +**Key props:** `items`, `open`, `disabled`, `openDirection`, `searcher`, `gridLayout`, `badgeIcons` +**Use cases:** Action lists anchored to a trigger. Supports hierarchy and lazy loading. + +--- + +## Media & Files + +### `limel-file-viewer` +Smart component that auto-detects and renders images, audio, video, text, PDF, office docs, email. + +**Key props:** `url`, `filename`, `allowDownload`, `allowFullscreen`, `officeViewer` +**Use cases:** Inline preview of attachments with optional download/fullscreen actions. + +### `limel-email-viewer` +Renders `.eml` email files with headers, body, and attachments. + +**Key props:** (used internally by file-viewer) +**Use cases:** Email preview within file-viewer. + +--- + +## Configuration + +### `limel-config` +Global configuration for icon paths, locale, markdown whitelist, and feature switches. + +**Key props:** `config` +**Use cases:** Place once at app root. Required for non-Lime-CRM applications. + +--- + +## Common Patterns + +### Events +All components emit `CustomEvent`. In JSX: +```tsx + { this.name = e.detail; }} +/> +``` + +### Slots +Use standard Web Component slots for content projection: +```tsx + +

Dialog body content

+ + +``` + +### Types +Import types from the package: +```ts +import { ListItem, Icon, FormSchema } from '@limetech/lime-elements'; +``` diff --git a/plugin/references/design-system.md b/plugin/references/design-system.md new file mode 100644 index 0000000000..6029512197 --- /dev/null +++ b/plugin/references/design-system.md @@ -0,0 +1,181 @@ +# lime-elements Design System Reference + +## Color System + +### Color Palettes + +The color system provides CSS custom properties that automatically adapt to light and dark themes. + +**20 base hues**, each with 5 variations: +`--color-{hue}-lighter` / `--color-{hue}-light` / `--color-{hue}-default` / `--color-{hue}-dark` / `--color-{hue}-darker` + +Available hues: red, pink, magenta, purple, deep-purple, indigo, blue, sky, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, coral, brown, grey. + +**Contrast swatches** (for neutral UI: backgrounds, containers, text): +`--contrast-100` through `--contrast-1700` (increments of 100). +These invert between light and dark modes. Never use them for colorful elements — use the color palette instead. + +**Special constants:** +- `--color-white` and `--color-black` do NOT change between modes. + +### Palette Tiers + +1. **UI palette** (10 swatches): Default choice for UI elements — provides semantic colors for status, errors, success, etc. Each hue has `-default` and `-light`. Use `-light` for hover states. +2. **Primary palette** (40 swatches): For icons, diagrams, and cases needing more variety. +3. **Extended palette** (100 swatches): For rich visualizations, charts, and illustrations. + +### Using Color Variables + +Colors are stored as **RGB triples without parentheses**: +```css +--color-blue-default: 33, 150, 243; +``` + +Usage: +```scss +// Solid color +color: rgb(var(--color-blue-default)); + +// With alpha +color: rgba(var(--color-blue-default), 0.1); +``` + +### Primary Accent Color + +Set one accent color for your product via: +```css +--lime-primary-color: 0, 150, 136; /* your brand color as RGB triple */ +``` + +This affects: primary buttons, checkboxes, radio buttons, input focus styles, selected/active states, and more. + +### Elevated Surfaces + +Use `--lime-elevated-surface-background-color` for cards, modals, and popovers. It automatically picks the right contrast for light/dark mode: +```scss +.my-card { + background-color: var(--lime-elevated-surface-background-color); +} +``` + +### Dark Mode + +Load `@limetech/lime-elements/dist/lime-elements/style/color-palette-extended.css` to enable dark mode support. Users' OS/browser preference is respected by default. Force a mode with: +```html + +``` + +### Color Philosophy + +- UI should be **neutrally colored** using contrast scales. Reserve color for meaning and attention. +- One accent color only. Colors communicate meaning — don't use them for decoration. +- Big surfaces (headers, backgrounds) should NOT be intensively colored. +- Brand colors exist (`--lime-brand-color-*`) but should be used sparingly (splash screens, logos). + +--- + +## Size Rhythms + +### The 4x Rule + +All spacing values (padding, margin, gap, width, height) must be **multiples of 4**: 4, 8, 12, 16, 20, 24, ... + +### Units: rem Only + +Use `rem` exclusively (1rem = 16px by default): +- 4px = 0.25rem +- 8px = 0.5rem +- 12px = 0.75rem +- 16px = 1rem +- 24px = 1.5rem +- 32px = 2rem + +SCSS helper: +```scss +@function pxToRem($px) { + @return #{$px/16}rem; +} +``` + +### The 1px Exception + +Always write `1px` for borders, never `0.0625rem`. Sub-pixel rems may not render correctly on all displays. + +### Other Exceptions to 4x + +- **font-size**: Typography has its own scaling needs; 13px or 14px are acceptable. +- **border-radius**: Pick the value that looks right. +- **box-shadow, blur**: Flexible for visual expression. +- Occasional small deviations (e.g., 6px padding) are fine if the overall structure stays in 4x rhythm. + +--- + +## Shadows and Depth + +### Purpose of Shadows + +Use shadows to: +- Signal interactivity (buttons look "pressable") +- Indicate hierarchy (modals float above content) +- Signal temporary elements (popovers, menus) +- Clarify movement direction during animations + +### Button Shadow Variables + +```scss +.my-button { + transition: box-shadow 0.2s ease, transform 0.1s ease-out; + box-shadow: var(--button-shadow-normal); + + &:hover { + box-shadow: var(--button-shadow-hovered); + } + &:active { + box-shadow: var(--button-shadow-pressed); + transform: translate3d(0, 0.08rem, 0); + } +} +``` + +### Surface Shadow Variables + +For floating UI elements (cards, modals, menus, popovers): use the surface shadow variables provided by lime-elements. These auto-adjust for dark mode. + +### State Shadow Variables + +Focus state shadows use `--lime-primary-color` (falling back to `--color-teal-default`). + +### When NOT to Use Shadows + +Do NOT use shadows just to create visually distinct sections. Instead use: +- Different background colors +- Outlines or dividers +- Larger headings +- Good layout with padding and margins + +Reserve shadows for: interactivity, hierarchy, and temporary elements. + +For inflated/emphasized sections (not buttons), use the inflated surface shadow variables with: +- Sizable `border-radius` +- Enough empty space around the element +- Light grey background (`--contrast-200` to `--contrast-400`) +- Parent surface slightly darker (`--contrast-400` to `--contrast-600`) + +--- + +## Decluttering and Cognitive Load + +### Philosophy + +> "Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away." — Antoine de Saint-Exupery + +Fewer elements on screen = less cognitive load = users spend mental energy on their task, not the UI. + +### Principles + +1. **Progressive disclosure**: Show details only when relevant. Input field helper text and character counters appear only on focus. +2. **Tooltips over labels**: Use tooltips for supplemental info users need only occasionally. +3. **Hide irrelevant buttons**: Disabled buttons that serve no informational purpose should be hidden until they become relevant. + - **Show disabled** when: user needs to know an action exists but can't use it yet (e.g., "Save" when form has errors). + - **Hide entirely** when: the action isn't relevant to the user's current intent (e.g., "Save" on a read-only display page). +4. **Question every element**: Is this needed? What's the trade-off of removing it? Does it add to clutter without adding functionality? diff --git a/plugin/references/interaction-patterns.md b/plugin/references/interaction-patterns.md new file mode 100644 index 0000000000..bf6b38d357 --- /dev/null +++ b/plugin/references/interaction-patterns.md @@ -0,0 +1,119 @@ +# lime-elements Interaction Patterns Reference + +## Switch vs. Checkbox + +**Rule of thumb:** +- **Switch**: Use when the toggle takes **immediate effect** without a submit/save action. +- **Checkbox**: Use when the user must **confirm or submit** their choices for them to take effect. + +Examples: +- Settings page toggle for dark mode → **Switch** (instant effect) +- Terms & conditions agreement in a form → **Checkbox** (submitted with form) + +--- + +## Labeling Boolean Fields + +Labels depend on context: + +### In Settings Pages +Label = the feature name (a noun). E.g., "Dark mode", "Notifications", "Auto-save". + +### In Forms +Label = a descriptive phrase or sentence. E.g., "I agree to the terms and conditions". Use helper text for clarification. + +### In Task Lists / Checklists +Label = a positively-phrased statement: +- Use prefixes like "is", "has", "can", "should" +- Avoid negatives: "Is active" not "Is not inactive" +- Be specific: "Subscribed for newsletters" not "Newsletter" + +### In Readonly Mode +Provide **two labels** (for true/false states) via `readonlyLabels`. A single label with just a visual toggle is ambiguous to readers. Enhance with icons and colors for clarity. + +**Best practices:** +1. Avoid single-noun labels in checklists/readonly +2. Use positive phrasing +3. Avoid negatives ("Is active" not "Is inactive") +4. Be specific about what the boolean represents +5. Consider context — "Is active" under a "Coworker" section should be "Is still working" + +--- + +## Disabled vs. Readonly + +These are distinct states with different semantics: + +### Disabled +- The field is **temporarily non-interactive** +- It **can become enabled** if the user changes something else in the UI +- Renders as a recognizable input field with visual dimming +- Implies: "You can't use this yet, but you might be able to soon" + +### Readonly +- The field is **permanently non-editable** regardless of user actions +- Used purely for **data visualization** — showing values the user cannot change +- Does NOT render as an interactive input element +- Implies: "This is display-only information" + +**When to use which:** +- User lacks permission to edit a field they can see → `readonly` +- Field depends on another field's value → `disabled` (until dependency is met) +- Showing computed or system-set values → `readonly` +- Feature not available in current plan/role → `readonly` + +--- + +## Hiding vs. Disabling Interactive Elements + +**When to hide:** +- The action is irrelevant to the user's current task or context +- Showing it would only add clutter without informational value +- The user has no reason to know the action exists right now + +**When to disable (but keep visible):** +- The user needs to know the action **exists** but can't use it yet +- The disabled state communicates what the user needs to do to enable it +- Removing it would be confusing (e.g., a "Save" button that appears/disappears) + +**Combined with visual hints:** +A disabled "Save" button should be accompanied by: +- Highlighted invalid fields +- Validation error messages +- Clear indication of what's blocking the action + +--- + +## Action Buttons + +### Placement (LTR layouts) +- Action buttons go in the **bottom-right** of dialogs/forms +- **Positive action** (Save, Next, Continue) → **right side** +- **Negative action** (Cancel, Back, Discard) → **left side** + +`limel-dialog` has a `slot="button"` flexbox that auto-aligns to the right. + +### Primary vs. Secondary +- Mark the expected/promoted action as `primary={true}` — it gets the theme's primary color +- For **risky or irreversible** actions, consider making the safer option primary instead + +### Label Best Practices +- Use **verbs** that describe the action: "Save", "Delete", "Send" — not "OK" or "Yes" +- Labels should make sense as a pair: "Save" / "Discard", "Confirm" / "Cancel" +- Be explicit: "Delete conversation" is better than "Delete" + +### Third Alternative (3 buttons) +For unsaved-changes prompts: "Save" (right) / "Discard" (right) / "Go back" (left, separated). +Push the back button left with: +```scss +.back-button { + justify-self: flex-start; + margin-right: auto; +} +``` + +### Colors and Icons +- Use colors to **communicate meaning**, not decoration +- Red for destructive actions, green for safe/positive ones +- Icons reinforce the label's meaning +- Don't over-emphasize secondary actions when the primary action isn't risky diff --git a/plugin/skills/accessibility/SKILL.md b/plugin/skills/accessibility/SKILL.md new file mode 100644 index 0000000000..f53c45f7ad --- /dev/null +++ b/plugin/skills/accessibility/SKILL.md @@ -0,0 +1,107 @@ +--- +name: lime-elements accessibility audit +description: Audit UI code for accessibility compliance — WCAG 2.1 AA, ARIA, keyboard navigation, focus management, and lime-elements-specific patterns (disabled vs readonly, hidden vs disabled). Triggers on requests to check accessibility, a11y audit, or WCAG compliance. +--- + +# lime-elements Accessibility Audit + +You are auditing UI code for accessibility, combining WCAG 2.1 AA standards with lime-elements-specific conventions. lime-elements components have built-in accessibility features, but consuming code must use them correctly. + +## Steps + +1. **Read the reference docs for lime-elements-specific patterns:** + - `${CLAUDE_PLUGIN_ROOT}/references/interaction-patterns.md` — disabled vs readonly, hidden vs disabled, boolean labeling + - `${CLAUDE_PLUGIN_ROOT}/references/component-catalog.md` — component props that affect accessibility + +2. **Read the user's code** thoroughly. + +3. **Audit against each category below.** For each issue, report: + - Severity: **Critical** (blocks users), **Major** (significant barrier), **Minor** (inconvenience) + - WCAG criterion (if applicable) + - What's wrong + - How to fix it + +### Perceivable (WCAG 1.x) + +**1.1 Text Alternatives** +- [ ] Images have meaningful `alt` text (or `alt=""` for decorative) +- [ ] Icon-only buttons have accessible labels (`label` prop on `limel-icon-button`) +- [ ] Charts and data visualizations have text alternatives + +**1.3 Adaptable** +- [ ] Content structure uses semantic HTML (headings, lists, tables) +- [ ] Information is not conveyed by color alone +- [ ] `limel-list` uses correct `type` for selection semantics + +**1.4 Distinguishable** +- [ ] Text meets 4.5:1 contrast ratio (3:1 for large text) +- [ ] Focus indicators are visible (lime-elements provides these via `--lime-primary-color`) +- [ ] Content is readable at 200% zoom +- [ ] No text in images + +### Operable (WCAG 2.x) + +**2.1 Keyboard Accessible** +- [ ] All interactive elements are keyboard reachable +- [ ] No keyboard traps +- [ ] Custom keyboard shortcuts don't conflict with browser/AT defaults +- [ ] `limel-dialog` traps focus correctly (built-in) and returns focus on close + +**2.4 Navigable** +- [ ] Page has a logical heading structure +- [ ] Focus order follows visual reading order +- [ ] `limel-breadcrumbs` provides navigation context +- [ ] Interactive elements have visible focus styles + +**2.5 Input Modalities** +- [ ] Touch targets are at least 44x44 CSS pixels +- [ ] `limel-file-dropzone` also provides click/keyboard alternative +- [ ] Gestures have single-pointer alternatives + +### Understandable (WCAG 3.x) + +**3.1 Readable** +- [ ] Language is set on the page (`lang` attribute) +- [ ] `limel-date-picker` and `limel-snackbar` receive correct `language` prop + +**3.2 Predictable** +- [ ] No unexpected context changes on focus or input +- [ ] Navigation is consistent +- [ ] `limel-switch` only used for instant-effect toggles (matches user expectation) + +**3.3 Input Assistance** +- [ ] Required fields have `required` prop set +- [ ] Error messages are descriptive (`helperText` on invalid fields) +- [ ] `invalid` prop is set on fields with errors +- [ ] `limel-form` validation errors are clearly associated with fields + +### Robust (WCAG 4.x) + +**4.1 Compatible** +- [ ] Custom elements follow Web Components standards (lime-elements handles this) +- [ ] ARIA roles and properties are used correctly +- [ ] No conflicting ARIA attributes + +### lime-elements-Specific Patterns + +**Disabled vs Readonly** +- [ ] `disabled` used for temporarily non-interactive fields (can become enabled) +- [ ] `readonly` used for permanently non-editable display-only fields +- [ ] Screen readers correctly announce both states (lime-elements handles this internally) + +**Hidden vs Disabled** +- [ ] Hidden elements are truly removed from DOM/tab order (not just visually hidden) +- [ ] Disabled buttons are visible when they inform the user about requirements +- [ ] Hidden actions don't break the user's mental model + +**Boolean Field Labels** +- [ ] Boolean fields have descriptive labels (not just nouns) +- [ ] `readonlyLabels` provided for readonly boolean fields +- [ ] Labels use positive phrasing ("Is active" not "Is not inactive") + +**Dialogs and Modals** +- [ ] `limel-dialog` receives a `heading` for screen readers +- [ ] Dialog content is meaningful without visual context +- [ ] Action buttons have descriptive verb labels (not "OK" / "Yes") + +4. **Summarize findings** with severity counts and prioritized fix list. diff --git a/plugin/skills/build/SKILL.md b/plugin/skills/build/SKILL.md new file mode 100644 index 0000000000..ab29934f57 --- /dev/null +++ b/plugin/skills/build/SKILL.md @@ -0,0 +1,44 @@ +--- +name: Build UI with lime-elements +description: Build user interfaces using lime-elements web components, applying the design system's color, sizing, shadow, and interaction conventions. Triggers on requests to build forms, pages, dialogs, or UIs with lime-elements. +--- + +# Build UI with lime-elements + +You are helping the user build a user interface using `@limetech/lime-elements`, a Stencil.js web component library. You will combine the lime-elements design system with your own UI/UX design, accessibility (WCAG 2.1 AA), and frontend best practices. + +## Steps + +1. **Read the reference docs** to ground your output in the design system: + - `${CLAUDE_PLUGIN_ROOT}/references/component-catalog.md` — find the right components + - `${CLAUDE_PLUGIN_ROOT}/references/design-system.md` — color, sizing, shadow, declutter rules + - `${CLAUDE_PLUGIN_ROOT}/references/interaction-patterns.md` — switch vs checkbox, disabled vs readonly, action buttons + +2. **Understand the user's requirements.** Ask clarifying questions if the scope is ambiguous. Identify: + - What data is being displayed or collected? + - What actions does the user need? + - What's the context (dialog, full page, card, form)? + +3. **Choose components.** Select the most appropriate `limel-*` components from the catalog. Prefer: + - `limel-form` for schema-driven forms over manually composing individual fields + - `limel-picker` for large/dynamic datasets, `limel-select` for small fixed lists + - `limel-switch` for instant-effect toggles, `limel-checkbox` for submit-to-apply + - `limel-dialog` for focused interactions, `limel-popover` for contextual options + +4. **Write the code.** Output working Stencil.js TSX (or framework-agnostic HTML if requested). Follow these conventions: + - **Colors:** Use CSS custom properties from the color system. Set `--lime-primary-color` for accent. Use `--lime-elevated-surface-background-color` for cards/modals. Use contrast scale for neutral UI. + - **Sizing:** All spacing in multiples of 4, using rem units. `1px` for borders only. + - **Shadows:** Use `--button-shadow-*` for buttons, surface shadow variables for cards/modals. Transition shadow changes smoothly. + - **Declutter:** Show details progressively. Hide disabled buttons that don't inform. Use tooltips for occasional info. + - **Action buttons:** Positive action on right, negative on left. Use verbs as labels. Mark primary action with `primary={true}`. + - **Accessibility:** Proper labels, ARIA attributes, keyboard navigation, focus management, sufficient contrast. + +5. **Explain your choices** briefly — which components you picked and why, and any design system rules you applied. + +## Key Reminders +- Events are `CustomEvent` — extract `event.detail` in handlers +- Use `slot="button"` for dialog action buttons +- Import types: `import { ListItem, Icon, FormSchema } from '@limetech/lime-elements'` +- Colors are RGB triples: `rgb(var(--color-blue-default))` +- One accent color only via `--lime-primary-color` +- UI should be neutrally colored — reserve color for meaning diff --git a/plugin/skills/component-guide/SKILL.md b/plugin/skills/component-guide/SKILL.md new file mode 100644 index 0000000000..5fafd12325 --- /dev/null +++ b/plugin/skills/component-guide/SKILL.md @@ -0,0 +1,61 @@ +--- +name: lime-elements component guide +description: Look up how to use a specific lime-elements component, find the right component for a use case, or get usage examples. Triggers on questions about limel-* components or "what component should I use for X". +--- + +# lime-elements Component Guide + +You are helping the user find and understand lime-elements components. You combine the component catalog with your own frontend knowledge to give practical, accurate guidance. + +## Steps + +1. **Read the component catalog:** + - `${CLAUDE_PLUGIN_ROOT}/references/component-catalog.md` + +2. **If the user asks about a specific component** (e.g., "how do I use limel-picker"): + - Find it in the catalog and summarize its purpose, key props, and events + - Show a practical code example in Stencil.js TSX + - Note any related components (e.g., limel-chip-set for managing the picker's selected values) + - Mention relevant design system conventions from `${CLAUDE_PLUGIN_ROOT}/references/interaction-patterns.md` if applicable + +3. **If the user asks "what component for X"** (e.g., "what component should I use for a toggle"): + - Search the catalog for matching components + - If multiple options exist, explain the trade-offs: + - `limel-switch` vs `limel-checkbox` (immediate vs submit-to-apply) + - `limel-select` vs `limel-picker` (fixed list vs dynamic search) + - `limel-dialog` vs `limel-popover` (modal vs contextual) + - Recommend the best fit with reasoning + +4. **Show example code** that demonstrates: + - Component markup with key props + - Event handling pattern (`CustomEvent`, extract `event.detail`) + - Slot usage where applicable + - Type imports + +## Key Patterns + +### Event Handling +```tsx +) => { + this.email = e.detail; + }} +/> +``` + +### Slots +```tsx + { this.isOpen = false; }}> +

Content goes in the default slot

+ + + +``` + +### Type Imports +```ts +import { ListItem, Option, FormSchema, Icon } from '@limetech/lime-elements'; +``` diff --git a/plugin/skills/design-review/SKILL.md b/plugin/skills/design-review/SKILL.md new file mode 100644 index 0000000000..3b7217de75 --- /dev/null +++ b/plugin/skills/design-review/SKILL.md @@ -0,0 +1,71 @@ +--- +name: lime-elements design review +description: Review UI code for compliance with the lime-elements design system — colors, sizing, shadows, interaction patterns, decluttering, and component usage. Triggers on requests to review UI, check design, or verify design system compliance. +--- + +# lime-elements Design Review + +You are reviewing UI code for compliance with the lime-elements design system. You combine the design system rules with your own UI/UX expertise to provide actionable feedback. + +## Steps + +1. **Read the reference docs:** + - `${CLAUDE_PLUGIN_ROOT}/references/design-system.md` + - `${CLAUDE_PLUGIN_ROOT}/references/interaction-patterns.md` + - `${CLAUDE_PLUGIN_ROOT}/references/component-catalog.md` + +2. **Read the user's code** thoroughly before commenting. + +3. **Check against each design system area.** For each issue found, provide: + - What's wrong + - Which rule it violates + - A specific fix + +### Color System Checklist +- [ ] Uses CSS custom properties, not hardcoded hex/rgb values +- [ ] Colors are written as `rgb(var(--color-xxx))` or `rgba(var(--color-xxx), alpha)` +- [ ] Uses `--lime-elevated-surface-background-color` for elevated surfaces +- [ ] Only one accent color via `--lime-primary-color` +- [ ] Neutral UI uses contrast scale, not intense colors on large surfaces +- [ ] Colors communicate meaning, not decoration + +### Sizing Checklist +- [ ] All spacing values are multiples of 4 (in rem) +- [ ] Uses rem units, not px (except for 1px borders) +- [ ] No `0.0625rem` for borders — use `1px` + +### Shadow Checklist +- [ ] Uses shadow CSS variables, not custom `box-shadow` values +- [ ] Shadow transitions are smooth (`transition: box-shadow 0.2s ease`) +- [ ] Shadows reserved for interactivity, hierarchy, temporary elements — not section dividers +- [ ] Button shadows use `--button-shadow-normal/hovered/pressed` + +### Interaction Patterns Checklist +- [ ] Switch for instant-effect, checkbox for submit-to-apply +- [ ] Boolean labels follow conventions (positive phrasing, context-appropriate) +- [ ] Disabled vs readonly used correctly (disabled = temporarily blocked, readonly = display only) +- [ ] Action buttons: positive right, negative left, verb labels +- [ ] Primary action is visually distinct; safer option may be primary for risky actions + +### Declutter Checklist +- [ ] Helper text and supplemental info shown only when relevant +- [ ] Disabled buttons hidden when they don't inform the user +- [ ] Tooltips used for occasional/supplemental info +- [ ] No unnecessary visual elements + +### Component Usage Checklist +- [ ] Correct component chosen for the use case (see catalog) +- [ ] Events handled via `CustomEvent` pattern +- [ ] Slots used correctly (e.g., `slot="button"` in dialogs) +- [ ] No misuse of internal/private components + +4. **Apply general UI/UX judgment** beyond the design system rules: + - Layout and visual hierarchy + - Consistency + - User flow and efficiency + - Error handling and feedback + +5. **Summarize findings** organized by severity: + - **Must fix:** Design system violations + - **Should fix:** UX improvements + - **Consider:** Nice-to-have enhancements From 5ed7371eae082c0c408ed2eb9629aef72679d130 Mon Sep 17 00:00:00 2001 From: John Traas Date: Fri, 20 Mar 2026 17:07:02 +0100 Subject: [PATCH 2/2] feat(plugin): add ui-assistant agent and standalone HTML quick-start Add orchestration agent (ui-assistant) that coordinates component selection, build, design review, and accessibility audit phases. Add quick-start.md reference with verified standalone HTML loading patterns (local dev, unpkg CDN, npm dist), required setup (limel-config, z-index variables, dark mode), and a complete minimal working example. Update build skill to ask Stencil vs standalone HTML and reference quick-start.md for the correct loading boilerplate. Add prerequisites section to component-catalog.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- plugin/README.md | 16 +++ plugin/agents/ui-assistant.md | 104 ++++++++++++++ plugin/references/component-catalog.md | 20 +++ plugin/references/quick-start.md | 185 +++++++++++++++++++++++++ plugin/skills/build/SKILL.md | 7 +- 5 files changed, 331 insertions(+), 1 deletion(-) create mode 100644 plugin/agents/ui-assistant.md create mode 100644 plugin/references/quick-start.md diff --git a/plugin/README.md b/plugin/README.md index 135644744f..155f1c4247 100644 --- a/plugin/README.md +++ b/plugin/README.md @@ -34,6 +34,21 @@ Audit UI code for WCAG 2.1 AA compliance, plus lime-elements-specific patterns l **Triggers on:** "check accessibility", "a11y audit", "WCAG compliance check" +## Agents + +### UI Assistant (`ui-assistant`) +An orchestration agent that coordinates all four skills into a structured, multi-phase workflow. It classifies your request, runs the relevant phases in order, and fixes any issues found during review. + +**Phases:** Component Selection → Build → Design Review → Accessibility Audit → Fix + +**Use it for:** +- Full build requests: "Build me a settings dialog with a switch and save button" +- Code reviews: "Review this form against the design system" +- Targeted audits: "Check accessibility on my dialog code" +- Component guidance: "What component should I use for file upload?" + +**Invoke with:** `@ui-assistant` or "use the ui-assistant agent" + ## Reference Docs The plugin bundles distilled design system knowledge in `references/`: @@ -41,6 +56,7 @@ The plugin bundles distilled design system knowledge in `references/`: - **`design-system.md`** — Color system (palettes, CSS variables, dark mode, accent color), size rhythms (4x rule, rem units), shadows (button/surface/state variables), declutter philosophy - **`component-catalog.md`** — All ~50 public components with tag names, key props, and use cases - **`interaction-patterns.md`** — Switch vs checkbox, disabled vs readonly, hidden vs disabled, action button placement and labeling +- **`quick-start.md`** — Standalone HTML loading pattern (required CSS/JS files, CDN URLs, limel-config setup, complete minimal working example) ## What This Plugin Does NOT Do diff --git a/plugin/agents/ui-assistant.md b/plugin/agents/ui-assistant.md new file mode 100644 index 0000000000..c52a5ccba2 --- /dev/null +++ b/plugin/agents/ui-assistant.md @@ -0,0 +1,104 @@ +--- +name: ui-assistant +description: > + Orchestrates lime-elements UI development — picks components, writes code, + reviews against the design system, and audits accessibility. Use for any + lime-elements UI task that benefits from a structured, multi-phase approach. +model: inherit +skills: + - build + - component-guide + - design-review + - accessibility +--- + +# lime-elements UI Assistant + +You are an orchestration agent for lime-elements UI development. You coordinate multiple phases of work — component selection, code generation, design review, and accessibility auditing — into a single coherent workflow. + +## Reference Documentation + +Before starting any phase, read the relevant reference docs: + +- `${CLAUDE_PLUGIN_ROOT}/references/component-catalog.md` — all ~50 public components with tag names, key props, and use cases +- `${CLAUDE_PLUGIN_ROOT}/references/design-system.md` — color system, sizing rhythms, shadows, declutter philosophy +- `${CLAUDE_PLUGIN_ROOT}/references/interaction-patterns.md` — switch vs checkbox, disabled vs readonly, action button conventions +- `${CLAUDE_PLUGIN_ROOT}/references/quick-start.md` — standalone HTML loading pattern, CDN URLs, minimal working example + +## Phases + +### 1. Guide Phase +**Purpose:** Identify the right lime-elements components for the task. +**When to run:** Any request that involves choosing or learning about components. +**What to do:** Follow the `component-guide` skill instructions. Search the component catalog, compare alternatives, and recommend the best fit with reasoning. +**Output:** A brief component plan — which components to use and why. + +### 2. Build Phase +**Purpose:** Write working UI code using lime-elements components. +**When to run:** Any request that involves creating or modifying UI code. +**What to do:** Follow the `build` skill instructions. Write Stencil.js TSX or standalone HTML depending on the user's needs. For standalone HTML output, read `quick-start.md` first and include the full loading boilerplate (all 3 files, limel-config, z-index variables). +**Output:** Working code with a brief explanation of design system rules applied. + +### 3. Review Phase +**Purpose:** Audit code against the lime-elements design system. +**When to run:** After building code, or when explicitly asked to review existing code. +**What to do:** Follow the `design-review` skill instructions. Check colors, sizing, shadows, interaction patterns, declutter principles, and component usage. +**Output:** Findings organized by severity (must fix, should fix, consider). + +### 4. Accessibility Phase +**Purpose:** Audit code for WCAG 2.1 AA compliance and lime-elements-specific patterns. +**When to run:** After building code, or when explicitly asked to audit accessibility. +**What to do:** Follow the `accessibility` skill instructions. Check perceivable, operable, understandable, and robust criteria, plus lime-elements patterns (disabled vs readonly, boolean labels, dialog headings). +**Output:** Findings with severity (critical, major, minor) and WCAG criteria. + +### 5. Fix Phase +**Purpose:** Address issues found in Review and Accessibility phases. +**When to run:** Automatically after Review and Accessibility phases find issues. +**What to do:** Apply fixes to the code, then briefly note what was changed and why. +**Output:** Updated code with a summary of fixes applied. + +## Request Routing + +Classify the user's request and run only the relevant phases, in order: + +| Request type | Phases | +|---|---| +| "Build me X" / "Create a Y" / "Implement Z" | Guide → Build → Review → Accessibility → Fix | +| "What component for X?" / "How do I use Y?" | Guide only | +| "Review my code" / "Check my UI" | Review + Accessibility | +| "Check accessibility" / "a11y audit" | Accessibility only | +| "Review against design system" | Review only | +| "Fix my UI issues" + code | Review → Accessibility → Fix | + +For ambiguous requests, default to the full pipeline (Guide → Build → Review → Accessibility → Fix). + +## Output Format + +Structure your response with clear phase headers so the user can follow the workflow: + +``` +## Component Selection +[Guide phase output] + +## Implementation +[Build phase output — the code] + +## Design Review +[Review phase findings] + +## Accessibility Audit +[Accessibility phase findings] + +## Fixes Applied +[What was changed to address review/a11y findings] +``` + +Skip headers for phases that don't apply to the request. + +## Guidelines + +- Read reference docs before starting — don't rely on assumptions about the design system. +- Be thorough in review phases but pragmatic — focus on real issues, not nitpicks. +- When fixing issues, explain the design system rule behind each fix so the user learns. +- If you're unsure about the user's requirements, ask clarifying questions before the Build phase rather than guessing. +- For large requests, outline your component plan first and confirm before writing all the code. diff --git a/plugin/references/component-catalog.md b/plugin/references/component-catalog.md index 4fec777cd1..6926993d8f 100644 --- a/plugin/references/component-catalog.md +++ b/plugin/references/component-catalog.md @@ -7,6 +7,26 @@ All components use the `limel-` tag prefix. They are Web Components (shadow DOM) --- +## Prerequisites + +Every page that uses lime-elements needs these resources loaded: + +1. **CSS:** `color-palette-extended.css` (color palette) + `lime-elements.css` (component styles) +2. **JS:** `lime-elements.esm.js` with `type="module"` +3. **Config:** A `` element with `iconPath` set: + ```html + + + ``` + +For the full loading pattern with CDN URLs and a complete working example, see [`quick-start.md`](quick-start.md). + +--- + ## Navigation & Layout ### `limel-dock` diff --git a/plugin/references/quick-start.md b/plugin/references/quick-start.md new file mode 100644 index 0000000000..de9467f749 --- /dev/null +++ b/plugin/references/quick-start.md @@ -0,0 +1,185 @@ +# lime-elements Quick Start — Standalone HTML + +How to load and use lime-elements **outside** of a Stencil project (plain HTML, prototyping, non-Stencil apps). + +--- + +## Required Files + +Every standalone page needs these **three** resources plus `limel-config`: + +| # | File | Purpose | +|---|------|---------| +| 1 | `color-palette-extended.css` | Full color palette (light + dark mode) | +| 2 | `lime-elements.css` | Component styles | +| 3 | `lime-elements.esm.js` | Component runtime (ES module) | +| 4 | `` element | Icon path + app-level config | + +Missing any of these will cause broken rendering, missing colors, or invisible icons. + +--- + +## Loading Patterns + +### Local development (from dev server) + +When running the lime-elements dev server (`npm start`): + +```html + + + +``` + +### From unpkg CDN + +For quick prototyping without a local build: + +```html + + + +``` + +Pin a version by replacing `@latest` with e.g. `@39.9.0`. + +### From npm dist (self-hosted) + +After `npm install @limetech/lime-elements`, the files are at: + +``` +node_modules/@limetech/lime-elements/dist/lime-elements/lime-elements.esm.js +node_modules/@limetech/lime-elements/dist/lime-elements/lime-elements.css +node_modules/@limetech/lime-elements/dist/lime-elements/style/color-palette-extended.css +``` + +--- + +## Required Setup + +### limel-config + +Place a `` element in the body and set its `config` property via JavaScript. This is **required** for icons to work: + +```html + + +``` + +### z-index variables + +Dialogs, popovers, and dropdowns need z-index variables. Add these in a ` +``` + +### Dark mode + +Add the `data-theme="dark"` attribute to the `` element: + +```html + +``` + +--- + +## Complete Minimal Example + +A full working HTML file with a single component: + +```html + + + + + + lime-elements Demo + + + + + + + + + + + + + + + + + + + + + +``` + +--- + +## Important: file:// Won't Work + +ES modules require an HTTP server. Opening the HTML file directly (`file://...`) will fail with CORS errors. Use any local server: + +```bash +npx serve . +# or +python3 -m http.server +``` + +--- + +## Event Handling in Vanilla JS + +lime-elements components emit `CustomEvent`. The value is always in `event.detail`: + +```js +const input = document.querySelector('limel-input-field'); +input.addEventListener('change', (event) => { + console.log('New value:', event.detail); +}); +``` + +To set object/array properties, use JavaScript (not HTML attributes): + +```js +const picker = document.querySelector('limel-picker'); +picker.searcher = async (query) => { + // return filtered items + return items.filter(i => i.text.includes(query)); +}; +``` diff --git a/plugin/skills/build/SKILL.md b/plugin/skills/build/SKILL.md index ab29934f57..5299dceb23 100644 --- a/plugin/skills/build/SKILL.md +++ b/plugin/skills/build/SKILL.md @@ -18,6 +18,7 @@ You are helping the user build a user interface using `@limetech/lime-elements`, - What data is being displayed or collected? - What actions does the user need? - What's the context (dialog, full page, card, form)? + - **Does the user want a Stencil component or standalone HTML?** Default to Stencil for projects that already use it. Default to standalone HTML for quick prototyping, demos, or non-Stencil projects. 3. **Choose components.** Select the most appropriate `limel-*` components from the catalog. Prefer: - `limel-form` for schema-driven forms over manually composing individual fields @@ -25,7 +26,11 @@ You are helping the user build a user interface using `@limetech/lime-elements`, - `limel-switch` for instant-effect toggles, `limel-checkbox` for submit-to-apply - `limel-dialog` for focused interactions, `limel-popover` for contextual options -4. **Write the code.** Output working Stencil.js TSX (or framework-agnostic HTML if requested). Follow these conventions: +4. **Write the code.** Output working Stencil.js TSX or standalone HTML depending on step 2. Follow these conventions: + + **For standalone HTML output:** Read `${CLAUDE_PLUGIN_ROOT}/references/quick-start.md` first. You **must** include the full loading boilerplate: all 3 files (color-palette-extended.css, lime-elements.css, lime-elements.esm.js), `limel-config` with iconPath, z-index variables, and a note about serving via HTTP (not file://). Use vanilla JS event listeners (`addEventListener`) instead of JSX handlers. + + For all output formats, follow these conventions: - **Colors:** Use CSS custom properties from the color system. Set `--lime-primary-color` for accent. Use `--lime-elevated-surface-background-color` for cards/modals. Use contrast scale for neutral UI. - **Sizing:** All spacing in multiples of 4, using rem units. `1px` for borders only. - **Shadows:** Use `--button-shadow-*` for buttons, surface shadow variables for cards/modals. Transition shadow changes smoothly.