From c9c4dbb46ba596b46380e7a72c1dec9a818a75e0 Mon Sep 17 00:00:00 2001 From: Anthony Rey Date: Thu, 11 Jun 2026 17:53:51 +0200 Subject: [PATCH] docs: add monorepo and package READMEs Add a slim root README indexing the published packages, and a consumer-facing README for @ippon-ui/styles, @ippon-ui/react and @ippon-ui/icons (npm install -D, canonical stylesheet imports, usage examples). Replaces the leftover Tikui and Vite scaffold READMEs in styles/ and react/. Bump the three published packages to 0.0.4 to release the new docs. Add the missing `mise build` step to the dev quickstart and to the pick-issue-to-pr skill setup. Refs #5 Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/skills/pick-issue-to-pr/SKILL.md | 2 +- README.md | 41 ++++++++ icons/README.md | 33 +++++++ icons/package.json | 2 +- react/README.md | 89 ++++++------------ react/package.json | 2 +- styles/README.md | 114 +++++------------------ styles/package.json | 2 +- 8 files changed, 127 insertions(+), 158 deletions(-) create mode 100644 README.md create mode 100644 icons/README.md diff --git a/.agents/skills/pick-issue-to-pr/SKILL.md b/.agents/skills/pick-issue-to-pr/SKILL.md index cb94f26..906828a 100644 --- a/.agents/skills/pick-issue-to-pr/SKILL.md +++ b/.agents/skills/pick-issue-to-pr/SKILL.md @@ -61,7 +61,7 @@ If the branch already exists, reuse it: `git worktree add "$WT" ""`. Do From the workspace root (only if a `mise.toml` exists there): ```bash -mise trust && mise install && mise setup +mise trust && mise install && mise setup && mise build ``` If the project doesn't use mise, run the project's documented install/setup instead. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4535b98 --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# Ippon UI + +Ippon's design system, distributed as a monorepo of independently published packages. + +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE) + +## Packages + +| Package | Description | Docs | +| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | +| [`@ippon-ui/styles`](https://www.npmjs.com/package/@ippon-ui/styles) | Pattern Library: design tokens and components as SCSS/CSS, built with [Tikui](https://tikui.org) following [Atomic Design](https://atomicdesign.bradfrost.com). | [styles/README.md](./styles/README.md) | +| [`@ippon-ui/react`](https://www.npmjs.com/package/@ippon-ui/react) | React component library wrapping the Pattern Library. | [react/README.md](./react/README.md) | +| [`@ippon-ui/icons`](https://www.npmjs.com/package/@ippon-ui/icons) | Icon font and types generated from [Ionicons](https://ionic.io/ionicons). | [icons/README.md](./icons/README.md) | + +## Development + +This repository uses [mise](https://mise.jdx.dev) to manage tooling and tasks. From the monorepo root: + +```sh +mise trust # trust the local mise configuration +mise install # install the pinned tools (Node, pnpm, Tikui CLI) +mise setup # install dependencies +mise build # build all packages +``` + +Common tasks: + +| Task | Command | +| --------------------------------------- | ------------------- | +| Start all packages in dev mode | `mise dev` | +| Develop the Pattern Library (port 4220) | `mise styles-dev` | +| Build all packages | `mise build` | +| Format | `mise format` | +| Lint | `mise lint` | +| Unit tests | `mise test-unit-ci` | + +See [`AGENTS.md`](./AGENTS.md) for the monorepo structure and conventions. + +## License + +[Apache-2.0](./LICENSE) © Ippon Technologies diff --git a/icons/README.md b/icons/README.md new file mode 100644 index 0000000..07f4f07 --- /dev/null +++ b/icons/README.md @@ -0,0 +1,33 @@ +# @ippon-ui/icons + +The Ippon UI icon font, generated from [Ionicons](https://ionic.io/ionicons). It ships the compiled font, its stylesheet and the TypeScript types of every available icon name. + +## Installation + +The font is bundled into your application, so install it as a dev dependency: + +```sh +npm install -D @ippon-ui/icons +``` + +## Usage + +In most cases you consume the icons through the higher-level packages: + +- the stylesheet is re-exported by [`@ippon-ui/styles`](https://www.npmjs.com/package/@ippon-ui/styles) as `@ippon-ui/styles/icons/ionicons.css`; +- the [`@ippon-ui/react`](https://www.npmjs.com/package/@ippon-ui/react) `IpponIcon` and `IpponIon` components render them by name. + +This package also exposes the icon names as types, so you can type your own props against the available icons: + +```ts +import type { IconClassic, IconLogo, IconVariant } from '@ippon-ui/icons'; + +type Icon = { + name: IconClassic | IconLogo; + variant?: IconVariant; // 'sharp' | 'outline' +}; +``` + +## License + +[Apache-2.0](./LICENCE) © Ippon Technologies diff --git a/icons/package.json b/icons/package.json index e5782a0..34ca1dc 100644 --- a/icons/package.json +++ b/icons/package.json @@ -1,6 +1,6 @@ { "name": "@ippon-ui/icons", - "version": "0.0.3", + "version": "0.0.4", "description": "Ippon UI Icons based on Ionicons", "repository": { "type": "git", diff --git a/react/README.md b/react/README.md index 66770df..a12f5ec 100644 --- a/react/README.md +++ b/react/README.md @@ -1,75 +1,42 @@ -# React + TypeScript + Vite +# @ippon-ui/react -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +The Ippon UI React component library, wrapping the [`@ippon-ui/styles`](https://www.npmjs.com/package/@ippon-ui/styles) Pattern Library. -Currently, two official plugins are available: +## Installation -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +The components render the Pattern Library markup, so they require `@ippon-ui/styles` alongside React 19. Both UI packages are bundled into your application, so install them as dev dependencies: -## React Compiler +```sh +npm install -D @ippon-ui/react @ippon-ui/styles +``` -The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information. +`react` and `react-dom` (`^19`) are peer dependencies provided by your application. -Note: This will impact Vite dev & build performances. +## Usage -## Expanding the ESLint configuration +Import the fonts, icons and stylesheet once in your application entry point: -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: +```ts +import '@ippon-ui/styles/fonts/open-sans/400.css'; +import '@ippon-ui/styles/fonts/open-sans/600.css'; +import '@ippon-ui/styles/fonts/open-sans/700.css'; +import '@ippon-ui/styles/fonts/saira-extra-condensed/700.css'; +import '@ippon-ui/styles/icons/ionicons.css'; +import '@ippon-ui/styles/tikui.css'; +``` -```js -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... +Then use the components: - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, +```tsx +import { IpponButton } from '@ippon-ui/react'; - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]); +export const SaveButton = () => ( + console.log('saved')}> + Save + +); ``` -You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: +## License -```js -// eslint.config.js -import reactX from 'eslint-plugin-react-x'; -import reactDom from 'eslint-plugin-react-dom'; - -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs['recommended-typescript'], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]); -``` +[Apache-2.0](./LICENCE) © Ippon Technologies diff --git a/react/package.json b/react/package.json index 0644714..3c0e7ef 100644 --- a/react/package.json +++ b/react/package.json @@ -1,7 +1,7 @@ { "name": "@ippon-ui/react", "description": "Ippon UI React Component Library", - "version": "0.0.3", + "version": "0.0.4", "license": "Apache-2.0", "repository": { "type": "git", diff --git a/styles/README.md b/styles/README.md index 86c8019..f66920b 100644 --- a/styles/README.md +++ b/styles/README.md @@ -1,107 +1,35 @@ -# Tikui +# @ippon-ui/styles -![Tikui logo](./logo.svg) +The Ippon UI Pattern Library: design tokens and components as SCSS/CSS, built with [Tikui](https://tikui.org) following [Atomic Design](https://atomicdesign.bradfrost.com). -Tikui is a MIT-licensed free software project allowing you to create a web pattern library. +## Installation -## Prerequisites +The package is bundled into your application, so install it as a dev dependency: -- [Node.js](https://nodejs.org) LTS version -- [pnpm](https://pnpm.io) -- [@tikui/cli](https://www.npmjs.com/package/@tikui/cli) (install it globally using `pnpm add -g @tikui/cli`) - -## Development - -### Install dependencies - -After cloning the repository, please run this command: - -```bash -mise install -``` - -And to install the dependencies: - -```bash -mise setup -``` - -### Serve - -In development, you can run the application locally on [localhost:3000](http://localhost:3000/) - -```bash -mise dev -``` - -### Create a component - -First of all, the source folder `src` follows the [Atomic Design](http://atomicdesign.bradfrost.com/table-of-contents/) methodology. - -Here is an example of how to create a `button` component: - -```bash -mise styles-create-component button -l atom +```sh +npm install -D @ippon-ui/styles ``` -> If you don't have the good level of information about the command, you can use the `help` command of `tikui`: -> -> - `tikui help` to see the global help -> - `tikui help create` to see a command help, here `create` - -You can add inside the `src/atom/atom.pug` file: - -```pug -include:componentDoc(height=55) button/button.md -``` - -> Note: [Pug](https://pugjs.org) is the template engine used by **Tikui** and indentations are important. - -> You can also use `include:templateDoc button/button.md` if you don't want to see the component render, it's useful on bigger components like templates. - -By default, there is only one style file in the `src` folder: `tikui.scss`. - -It's because you're free to create your own structure even if we recommend you to follow the Atomic Design methodology. - -So you may need to create the file: - -```bash -touch src/atom/_atom.scss -``` - -And then, inside `tikui.scss`: - -```scss -@use 'atom/atom'; -``` - -Inside `src/atom/_atom.scss`: - -```scss -@use 'button/button'; -``` +## Usage -And inside `button.mixin.pug`: +Import the fonts, icons and the compiled stylesheet once in your application entry point: -```pug -mixin ippon-button - button.ippon-button Button +```ts +import '@ippon-ui/styles/fonts/open-sans/400.css'; +import '@ippon-ui/styles/fonts/open-sans/600.css'; +import '@ippon-ui/styles/fonts/open-sans/700.css'; +import '@ippon-ui/styles/fonts/saira-extra-condensed/700.css'; +import '@ippon-ui/styles/icons/ionicons.css'; +import '@ippon-ui/styles/tikui.css'; ``` -Inside `src/atom/button/_button.scss`: +Then use the CSS classes in your markup. Classes follow an alternative-prefix convention: a base class plus `-` modifiers. -```scss -.ippon-button { - border: 1px solid #47a; - border-radius: 3px; - background-color: #47a; - padding: 5px; - line-height: 1.5rem; - color: #fff; - font-size: 1rem; -} +```html + +Done ``` -As you can see in the browser, there is a documented blue button with an example of code. +## License -More info can be found in the [component documentation](https://tikui.org/doc/component-doc.html) of **Tikui**. +[Apache-2.0](./LICENCE) © Ippon Technologies diff --git a/styles/package.json b/styles/package.json index d66ad83..5d17ed1 100644 --- a/styles/package.json +++ b/styles/package.json @@ -1,6 +1,6 @@ { "name": "@ippon-ui/styles", - "version": "0.0.3", + "version": "0.0.4", "description": "Ippon UI Pattern Library", "repository": { "type": "git",