@ippon-ui/ui 0.0.2

package/.agents/agents/component-library-create-from-pattern-library.agent.md

@@ -0,0 +1,37 @@
+---
+name: component-library-create-from-pattern-library
+description: Create a component in the Component Library based on a component from the Pattern Library
+skills:
+  - component-library
+  - pattern-library
+---
+
+## Task
+
+As input, you are given the component name to create in the Component Library (based on an existing Pattern Library component).
+
+## Steps
+
+1. Check if a component already exists in `react/src/` that covers this need by searching for existing `Ippon<ComponentName>` components
+
+2. Read the Pattern Library component documentation from the node module `@ippon-ui/styles` located in `node_modules/@ippon-ui/styles/dist`:
+   - Locate `src/<level>/<component-name>/<component-name>.mixin.pug` (where `<level>` is atom, molecule, organism, or template)
+   - Understand the HTML structure, alternatives (CAP `-variant`), and parts (CAP `--part`)
+   - Read `<component-name>.md` for component details
+
+3. Write unit tests in `react/test/Ippon<ComponentName>.spec.tsx`:
+   - Create tests for all expected props: variants, colors, sizes
+   - Include tests for children rendering and `dataSelector` binding
+   - Follow the test structure from Component Library "Unit Tests" section
+   - Run `cd app && pnpm test:unit` to verify tests are red before implementing
+
+4. Implement the React component in `react/src/Ippon<ComponentName>.tsx`:
+   - Follow the structure and conventions from Component Library "Creating a Component" section
+   - Type props using `DataSelectable` or `DataSelectableWithChildren`
+   - Build CSS classes using `clsx` and helpers from `CAP.ts`
+   - Create sub-components for any parts (CAP `--part`)
+   - Run tests with `cd app && pnpm test:unit` until all tests pass
+
+5. Export the component from `react/src/index.ts`:
+   - Add `export { IpponComponent } from './IpponComponent.tsx';`
+   - If applicable, also export any sub-components or parts

package/.agents/agents/patten-library-create-component.agent.md

@@ -0,0 +1,30 @@
+---
+name: pattern-library-create-component
+description: Create a component on the Pattern Library
+skills:
+  - pattern-library
+---
+
+## Task
+
+As input, you are given the level and name of the component to create.
+
+## Steps
+
+1. Review the instructions in `.github/instructions/pattern-library.instructions.md` to understand:
+   - The Atomic Design principles (atoms, molecules, organisms, templates)
+   - The Tikui component architecture
+   - The CAP (Component Alternative Part) naming convention
+   - Token and Quark concepts
+
+2. Generate the component using the tikui command with the proper format:
+
+   ```shell
+    mise styles-create-component <component> --path <path>
+   ```
+
+   Where:
+   - `<component>` is the component name in `kebab-case`
+   - `<path>` where default is 'atom' to create inside `src/atom`
+
+3. Ensure the generated component follows the CAP convention for alternatives and parts

package/.agents/skills/component-library/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: 'component-library'
+description: 'Component Library with React components used by the application.'
+---
+
+# Component Library
+
+Component Library is a part of react folder, you can find it in the `react/src` folder.
+
+It's a bounded context dedicated to React Components.
+
+## Concept
+
+The Component Library concept is not especially linked to a technology. The idea is to represent the mechanical part of each component.
+
+It therefore provides React components that will be consumed by another bounded context.
+
+## Integration with Pattern Library
+
+The Component Library consume the Pattern Library, it uses the provided documentation to know classes and structure to use for each component. The CSS is linked using a `link` tag in the `index.html` file of the React application.
+
+When implementing a component in the Component Library:
+
+1. Refer to the Pattern Library documentation for the correct CSS classes and structure
+2. Follow the CAP (Component Alternative Part) naming convention for variants and parts
+3. Use the semantic colors and tokens defined in the Pattern Library
+4. Ensure visual consistency by adhering to the Atomic Design hierarchy (atoms, molecules, organisms)
+
+## Creating a Component
+
+### File Organization
+
+Each component is defined by:
+
+- **Component file**: `react/src/Ippon<ComponentName>.tsx` (PascalCase)
+- **Test file**: `react/test/Ippon<ComponentName>.spec.tsx`
+- **Export**: added to `react/src/index.ts`
+
+### React Component Structure
+
+A component file follows this structure:
+
+```typescriptreact
+import type { DataSelectableWithChildren } from './DataSelectable.ts';
+import { clsx } from 'clsx';
+import { optionalToAlternativeClass } from './CAP.ts';
+
+type IpponComponentProps = DataSelectableWithChildren<{
+  variant?: 'primary' | 'secondary';
+  color?: IpponTokenTextColor;
+}>;
+
+export const IpponComponent = (props: IpponComponentProps) => (
+  <div
+    className={clsx(
+      'ippon-component',
+      optionalToAlternativeClass(props.variant),
+      optionalToAlternativeClass(props.color),
+    )}
+    data-selector={props.dataSelector}
+  >
+    {props.children}
+  </div>
+);
+```
+
+### Key Conventions
+
+#### Props Typing
+
+- Extend `DataSelectable<T>` for components without children
+- Extend `DataSelectableWithChildren<T>` for components with children
+- Always include `dataSelector?: string` (via `DataSelectable`)
+- Use types from `Tokens.ts` for colors and sizes (e.g., `IpponTokenTextColor`, `IpponTokenSize`)
+- Model alternatives (CAP `-variant`) as union types
+- Model booleans like `border` or `placeholder` as optional props
+
+#### CSS Class Building
+
+- Use `clsx()` from the `clsx` library to conditionally build class names
+- Import helpers from `CAP.ts`:
+  - `optionalToAlternativeClass(value)` → converts `'primary'` to `'-primary'`
+  - `optionalToPrefixedAlternativeClass(prefix)(value)` → converts `'l1'` with prefix `'shadow'` to `'-shadow-l1'`
+  - `toAlternativeClass(value)` → always converts to alternative class (non-optional)
+
+#### Parts and Sub-components
+
+If the Pattern Library component has parts (CSS classes like `ippon-component--part`):
+
+- Create a dedicated sub-component `IpponComponentPart` for parts with significant props
+- Export both the main component and the part(s) from the same file
+- Use `clsx('ippon-component--part', ...)` for part class names
+
+Example with slots:
+
+```typescriptreact
+export const IpponVSpaceSlot = (props: IpponVSpaceSlotProps) => (
+  <div
+    className={clsx('ippon-v-space--slot', optionalToAlternativeClass(props.align))}
+    data-selector={props.dataSelector}
+  >
+    {props.children}
+  </div>
+);
+```
+
+#### Exporting Components
+
+Add each new component to `react/src/index.ts`:
+
+```typescript
+export { IpponComponent } from './IpponComponent.tsx';
+export { IpponComponentPart } from './IpponComponent.tsx'; // if applicable
+```
+
+### Unit Tests
+
+Tests are located in `react/test/` and use Vitest + Testing Library.
+
+#### Running Tests
+
+```shell
+cd react
+
+pnpm test:unit:ci
+```
+
+#### Test Structure
+
+Each component test should:
+
+1. Verify the component renders with the correct base class name
+2. Test each prop variant (alternatives, colors, sizes)
+3. Test children rendering
+4. Test `dataSelector` binding
+5. Test custom HTML tags if applicable (via `tag` prop)
+
+Example test:
+
+```typescriptreact
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, configure, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { IpponComponent } from '../src';
+
+configure({
+  testIdAttribute: 'data-selector',
+});
+
+describe('IpponComponent', () => {
+  afterEach(cleanup);
+
+  it('should be like pattern library', () => {
+    render(<IpponComponent dataSelector="ippon-component">Content</IpponComponent>);
+
+    const component = screen.getByTestId('ippon-component');
+
+    expect(component).toHaveClass('ippon-component');
+  });
+
+  it.each(['primary', 'secondary'] as const)('should have variant %s', (variant) => {
+    render(<IpponComponent variant={variant} dataSelector="ippon-component" />);
+
+    const component = screen.getByTestId('ippon-component');
+
+    expect(component).toHaveClass(`-${variant}`);
+  });
+});
+```

package/.agents/skills/pattern-library/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: 'pattern-library'
+description: 'Pattern Libreary which allows representing graphical components. Provides CSS and uses HTML as a template language. This is where tokens, quarks, atoms, molecules, organisms, templates are defined.'
+---
+
+# Pattern Library
+
+The Pattern Library allows representing graphical elements.
+
+The Pattern Library concept is not especially linked to a technology. The idea is to represent the visual part of each component, the states but not the mechanical part.
+
+In the project, the Pattern Library applies to the web.
+
+It therefore provides:
+
+- CSS that will be consumed by another application
+- Documentation for each component with:
+  - A description of the component
+  - A rendering of the component
+  - The source code of the component (HTML and pug)
+
+So it's possible to consume the Pattern Library in any web application, regardless of the technology used (React, Vue, Angular, etc…).
+
+It is organized following Atomic Design.
+
+[Tikui](https://tikui.org/) is used to generate the documentation of the Pattern Library.
+
+## Component
+
+A component in Tikui is defined according to the following architecture:
+
+```
+<component>/
+  <component>.mixin.pug
+  <component>.code.pug
+  <component>.render.pug
+  _<component>.scss
+```
+
+The command to generate a component is as follows:
+
+```shell
+mise styles-create-component <component> --path <path>
+```
+
+- `<component>` is the name of the component, in `kebab-case`
+- `<path>` is the path to the folder where the component will be created, default is `atom` to create inside `src/atom`
+- The prefix is `ippon` using `mise`
+
+To generate the `Button` atom with the `ippon` prefix:
+
+```shell
+mise styles-create-component button --path atom
+```
+
+- ippon is used as the prefix
+- button is the name of the component
+- src/atom is the path to the folder where the component (atom) will be created
+
+## Atomic Design
+
+Atomic Design is proposed by Brad Frost. The idea is to hierarchically compose graphical components into five levels:
+
+- Atoms: indivisible elements such as a button, form field, or icon
+- Molecules: groups of atoms to compose to form small components
+- Organisms: groups of molecules to assemble to form more complex elements
+- Templates: groups of organisms, molecules, or atoms to assemble to form pages
+- Pages: instances of templates with real content (it is the applications consuming the Pattern Library that will create the pages)
+
+In Tikui, these concepts are represented by folders:
+
+```
+src/
+  atom/
+    atom.pug
+    _atom.scss
+  molecule/
+    molecules.pug
+    _molecule.scss
+  organism/
+    organism.pug
+    _organism.scss
+  template/
+    template.pug
+    _template.scss
+  index.pug
+  tikui.scss
+```
+
+## CAP
+
+A component follows CAP (Component Alternative Part):
+
+- Component: the name of the component in `kebab-case`
+- Alternative: an alternative of the component or a part that starts with a `-`, followed by the name of the alternative in `kebab-case`
+- Part: a part of the component or an alternative that starts with `--`, followed by the name of the part in `kebab-case`
+
+An example with a button:
+
+In SCSS:
+
+```scss
+.ippon-button {
+  // button styles
+
+  &.-primary {
+    // primary alternative styles
+  }
+
+  &.-secondary {
+    // secondary alternative styles
+  }
+
+  &--icon {
+    // icon part styles
+  }
+
+  &--text {
+    // text part styles
+  }
+}
+```
+
+In HTML:
+
+```html
+<button class="ippon-button -primary">
+  <span class="ippon-button--icon">Icon</span>
+  <span class="ippon-button--text">Text</span>
+</button>
+```
+
+## Tikui
+
+To document with Tikui, simply include the component's Markdown file in the file where you want to document it.
+
+You will use:
+
+- `componentDoc` for atoms, molecules, and organisms
+  - A size can be specified for the component rendering with the `height` option (example: `height=300`)
+- `templateDoc` for templates
+  - There is no size since the rendering area represents a button to go to the rendering
+
+For a `Button` atom:
+
+```pug
+include:componentDoc(height=300) button/button.md
+```
+
+For a `Layout` template:
+
+```pug
+include:templateDoc layout/layout.md
+```
+
+## Token
+
+A token is a style property. This can be a color, a font, a spacing, etc… It's a concept, so, even if it's possible to use variables to represent tokens, it's important to not confuse tokens and variables.
+
+In the Patten Library, tokens are defined inside the `tokens` folder:
+
+```
+src/
+  token/
+    _token.scss
+    token.pug
+```
+
+### Color
+
+A color token can be directly the color with a quantity represented by a number from 0 to 999.
+
+For the color `green`, it can be represented by the following tokens:
+
+```
+--ippon-color-green-100, --ippon-color-green-200, --ippon-color-green-300, --ippon-color-green-400, --ippon-color-green-500, --ippon-color-green-600, --ippon-color-green-700, --ippon-color-green-800, --ippon-color-green-900
+```
+
+But it stills a base color, the base color itself can't be used directly for a component, it must be used by a semantic color.
+
+#### Semantic color
+
+A semantic color is a color token that represents a meaning. For example, the `positive` semantic color use the `green` base color. The `semantic` color has also a quantity.
+
+Here is an example for the `positive` semantic color:
+
+```scss
+:root {
+  --ippon-color-positive-100: var(--ippon-color-green-100);
+  --ippon-color-positive-200: var(--ippon-color-green-200);
+  --ippon-color-positive-300: var(--ippon-color-green-300);
+  --ippon-color-positive-400: var(--ippon-color-green-400);
+  --ippon-color-positive-500: var(--ippon-color-green-500);
+  --ippon-color-positive-600: var(--ippon-color-green-600);
+  --ippon-color-positive-700: var(--ippon-color-green-700);
+  --ippon-color-positive-800: var(--ippon-color-green-800);
+  --ippon-color-positive-900: var(--ippon-color-green-900);
+}
+```
+
+Another level of semantic color exists, more relative to the usage. There is the following semantic color groups:
+
+- `surface`
+- `text-icon`
+- `border`
+
+It's also possible to find alternatives like 'primary', 'secondary', 'tertiary', etc…
+
+So it's possible to define a text or icon color `on` a surface color, for example `on-primary` or `on-secondary`.
+
+Here is an example for the `success` semantic color:
+
+```scss
+:root {
+  --ippon-color-success-surface-primary: var(--ippon-color-positive-700);
+  --ippon-color-success-surface-primary-hover: var(--ippon-color-positive-800);
+  --ippon-color-success-surface-primary-active: var(--ippon-color-positive-900);
+  --ippon-color-success-surface-secondary: var(--ippon-color-positive-100);
+  --ippon-color-success-surface-secondary-hover: var(--ippon-color-positive-200);
+  --ippon-color-success-surface-secondary-active: var(--ippon-color-positive-300);
+  --ippon-color-success-text-icon-primary: var(--ippon-color-positive-600);
+  --ippon-color-success-text-icon-secondary: var(--ippon-color-positive-800);
+  --ippon-color-success-text-icon-on-primary: var(--ippon-color-neutral-0);
+  --ippon-color-success-text-icon-on-secondary: var(--ippon-color-positive-700);
+  --ippon-color-success-border: var(--ippon-color-positive-500);
+}
+```
+
+## Quark
+
+A quark is a portion of an atom, molecule, or organism that is not usable without being part of a component. Generally, we use SCSS `@mixin` to represent quarks but it's not mandatory, it's a concept. For example, for a `Text` and a `Title` atom, we can imagine a set quark to represent weight alternatives:
+
+```scss
+@mixin weights {
+  &.-light {
+    font-weight: 300;
+  }
+
+  &.-regular {
+    font-weight: 400;
+  }
+
+  &.-medium {
+    font-weight: 500;
+  }
+
+  &.-bold {
+    font-weight: 700;
+  }
+}
+```
+
+So it's possible to use this `weights` quark for both `Text` and `Title` atoms:
+
+**Text:**
+
+```scss
+.ippon-text {
+  @include weights;
+}
+```
+
+**Title:**
+
+```scss
+.ippon-title {
+  @include weights;
+}
+```
+
+In the Pattern Library, quarks are defined in the `quark` folder:
+
+```
+src/
+  quark/
+    _quark.scss
+```

package/.github/workflows/build.yml

@@ -0,0 +1,34 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24.14.1
+          cache: pnpm
+      - run: pnpm -r install --frozen-lockfile
+      - run: pnpm format:ci
+      - run: pnpm lint:ci
+      - run: pnpm test:unit:ci
+      - run: pnpm build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts
+          path: |
+            icons/dist
+            icons/types
+            styles/dist
+          retention-days: 1

package/.gitlab-ci.yml

@@ -0,0 +1,12 @@
+include:
+  - local: 'ci/common.yml'
+  - local: 'ci/build.yml'
+  - local: 'ci/deploy.yml'
+
+default-build:
+  stage: build
+  script:
+    - echo "Nothing to build"
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: never

package/.prettierignore

@@ -0,0 +1,6 @@
+/*/dist/
+/pnpm-lock.yaml
+/icons/svg/
+/styles/.tikui-cache/
+/icons/types/
+/.pnpm-store/

package/AGENTS.md

@@ -0,0 +1,50 @@
+Code must be in English.
+
+## Monorepo Structure
+
+The project is a monorepo composed of the following projects:
+
+- **styles**: Contains a Pattern Library with visual components, organized following Atomic Design.
+- **icons**: Allows generating an icon font from SVG files from Ionicons
+
+## Commands
+
+You should use `mise` to run commands linked to this project. If you need to add more operations or a new command, please edit the `mise.toml` file, so the command will be available.
+
+Run from the **monorepo root** unless noted otherwise.
+
+| Task                         | Command             |
+| ---------------------------- | ------------------- |
+| Trust mise                   | `mise trust`        |
+| Install mise                 | `mise install`      |
+| Install dependencies         | `mise setup`        |
+| Start all in dev mode        | `mise dev`          |
+| Build all packages           | `mise build`        |
+| Format (fix)                 | `mise format`       |
+| Format (check only)          | `mise format-ci`    |
+| Lint (fix)                   | `mise lint`         |
+| Lint (check only)            | `mise lint-ci`      |
+| Unit tests (not interactive) | `mise unit-test-ci` |
+
+## Pattern Library (`styles`)
+
+The Pattern Library uses [Tikui](https://tikui.org) and follows [Atomic Design](http://atomicdesign.bradfrost.com/table-of-contents/):
+
+```
+src/
+  quark/     # SCSS variables, mixins, fonts reused inside atoms/molecules/organisms (no rendered output)
+  token/     # Design tokens (colors, shadows, typography, sizes)
+  atom/      # Smallest components: badge, button, icon, ion, meter, text, title, tab
+  molecule/  # Composed atoms: import-file, tabs, toggle
+  organism/  # Layout-level components: card, container, h-space, v-space, grid, header, modal, button-card
+  template/  # Full page layouts
+```
+
+CSS class naming uses an alternative-prefix convention: base class + `-<modifier>` (e.g. `ippon-card -shadow-2 -border`).
+
+To develop the Pattern Library: `mise styles-dev` (serves on port 4220).
+
+To add a component: `mise styles-create-component <component> --path <path>` where:
+
+- component: component name in `kebab-case` (e.g. `button-card`)
+- path: default is 'atom' to create inside `src/atom` from the styles directory