@cloudwick/icons 1.0.1 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,6 +6,10 @@ The set is design-system agnostic. It carries no CSS framework, no theme file an
6
6
  stylesheet import, so it drops into any Cloudwick project — internal or external —
7
7
  without assuming anything about how that project is styled.
8
8
 
9
+ To find an icon, use the icons site: search the set, preview an icon and copy it as a
10
+ React component or a plain SVG. Its Usage page runs every pattern below live. The source
11
+ is in [`site/`](site/).
12
+
9
13
  ## Install
10
14
 
11
15
  ```bash
@@ -76,6 +80,9 @@ forwarded to the `<svg>`, and the ref lands there too.
76
80
  <IconZap /> {/* decorative */}
77
81
  ```
78
82
 
83
+ Tailwind's preflight sets every `<svg>` to `display: block`, so an icon placed inside a
84
+ line of text starts a new line. Give such an icon `className="inline"`.
85
+
79
86
  ### Animating an icon
80
87
 
81
88
  The package ships no CSS, so it has no animation props. `className` and `style` reach the
@@ -136,6 +143,47 @@ declare module '*.svg' {
136
143
  }
137
144
  ```
138
145
 
146
+ ### Icon manifest for tools and agents
147
+
148
+ `@cloudwick/icons/manifest.json` lists every icon with what an import needs and what a
149
+ search needs. Read it to find an icon by concept ("delete" finds the trash icons) instead
150
+ of guessing at filenames. In a script or tool, read it at runtime and type it with
151
+ `IIconManifest`:
152
+
153
+ ```ts
154
+ import { readFile } from 'node:fs/promises';
155
+ import { createRequire } from 'node:module';
156
+ import type { IIconManifest } from '@cloudwick/icons';
157
+
158
+ const file = createRequire(import.meta.url).resolve('@cloudwick/icons/manifest.json');
159
+ const manifest: IIconManifest = JSON.parse(await readFile(file, 'utf8'));
160
+ ```
161
+
162
+ A static `import manifest from '@cloudwick/icons/manifest.json' with { type: 'json' }` works
163
+ too, but TypeScript then infers a type from the whole 1.3 MB file, and that type has plain
164
+ `string` where `IIconManifest` has `TIconName`. The file is also at
165
+ `node_modules/@cloudwick/icons/manifest.json` for tools that just open it. Each entry looks
166
+ like this:
167
+
168
+ ```json
169
+ { "slug": "3d-rotate-filled", "component": "Icon3dRotateFilled",
170
+ "import": "@cloudwick/icons/Icon3dRotateFilled", "svg": "@cloudwick/icons/svg/3d-rotate-filled.svg",
171
+ "category": "Iconography", "variant": "filled", "family": "3d-rotate", "keywords": ["..."] }
172
+ ```
173
+
174
+ | Field | Meaning |
175
+ | --- | --- |
176
+ | `slug` | SVG filename without `.svg`; the component name is `Icon` + its PascalCase |
177
+ | `component`, `import` | The export and its deep-import specifier |
178
+ | `svg` | The optimized raw SVG |
179
+ | `category` | The Figma frame the icon sits in; `Uncategorized` when there is none |
180
+ | `variant`, `family` | `filled`/`outline` when the slug ends in one and the other style is published too (otherwise `null`), and the slug without that suffix, so the two siblings share a `family` |
181
+ | `keywords` | Search terms beyond the slug's own words: the Figma component description plus synonyms from [`src/keywords.json`](src/keywords.json) |
182
+
183
+ The top level also carries `schemaVersion`, `count` and the sorted `categories`. The
184
+ icons site serves the same data at <https://cw-icons.amorphic.link/icons.json>, with usage
185
+ notes for language models at <https://cw-icons.amorphic.link/llms.txt>.
186
+
139
187
  ### Choosing an icon by name at runtime
140
188
 
141
189
  If the names come from a set you know when you write the code (a status, a nav config, a
@@ -216,20 +264,22 @@ the type-check and the release workflow skips building and publishing.
216
264
 
217
265
  ```
218
266
  .github/workflows/
219
- ci.yml on pull request: tests, type-check
267
+ ci.yml on pull request: tests, type-check, the site's checks
220
268
  sync-icons.yml manual dispatch: run sync, open a PR
221
269
  release.yml on merge to main: build, version, publish
270
+ site.yml after a release or a site change: deploy the icons site
222
271
 
223
272
  scripts/ TypeScript, compiled by tsc to scripts/.build/, never published
224
273
  sync-icons.ts Figma API -> raw-svgs/ + manifest.json
225
274
  open-sync-pr.ts commits the sync output and opens its PR, in CI
226
- build-icons.ts raw-svgs/ -> components/ + svg/
275
+ build-icons.ts raw-svgs/ -> components/ + svg/ + manifest.json
227
276
  lib/ the naming, walk, classify and build rules and the Figma
228
277
  and GitHub API clients, unit-tested
229
278
 
230
279
  src/
231
280
  raw-svgs/ TRACKED written by sync-icons.ts
232
- manifest.json TRACKED node id, name, hash per icon
281
+ manifest.json TRACKED node id, name, category, description, hash per icon
282
+ keywords.json TRACKED hand-edited synonym groups and per-icon search terms
233
283
  components/ IGNORED written by build-icons.ts: one .tsx per icon,
234
284
  index.ts barrel, registry.ts for dynamic.tsx
235
285
  props.ts hand-written size tokens, IIconProps
@@ -238,7 +288,12 @@ src/
238
288
  index.ts hand-written package entry point
239
289
 
240
290
  svg/ IGNORED raw-svgs after SVGO, own colors kept, published
291
+ manifest.json IGNORED the public manifest, published as ./manifest.json
241
292
  dist/ IGNORED tsc output, published
293
+
294
+ site/ the icons site: its own npm project, never published
295
+ vite/iconIndex.ts build-time index of the published icons + manifest categories
296
+ src/examples/ one live usage example per file, shown with its own source
242
297
  ```
243
298
 
244
299
  ### Running the pipeline locally
@@ -258,6 +313,56 @@ npm run build # tsc -> dist/
258
313
  A local sync is for trying changes out. Do not commit its `raw-svgs/` or `manifest.json`;
259
314
  the workflow's pull request is the only way they change.
260
315
 
316
+ ### Icons site
317
+
318
+ `site/` is a Vite app built with astral-ui and Tailwind. It shows the icons from the
319
+ published `@cloudwick/icons` on npm, not the local build, so it always matches what
320
+ consumers install.
321
+
322
+ It runs on the Node versions Vite supports (20.19+ or 22.12+); `nvm use` at the repository
323
+ root picks the repo's Node 22 from `.nvmrc`.
324
+
325
+ ```bash
326
+ nvm use
327
+ cd site
328
+ npm ci
329
+ npm run dev
330
+ ```
331
+
332
+ Before a pull request, run `npm run lint`, `npm run typecheck`, `npm test` and
333
+ `npm run build` there; CI runs the same. Scope commits that only touch the site as
334
+ `site` (`feat(site): ...`), so they don't release the npm package.
335
+
336
+ #### Deploying the icons site
337
+
338
+ The **Deploy icons site** workflow (`site.yml`) publishes `site/` to AWS Amplify:
339
+
340
+ - after each release, showing the version just released;
341
+ - on a push to `main` that changes `site/`, showing the latest version;
342
+ - on a manual run, optionally for a version you name.
343
+
344
+ npm serves a new version a little after `semantic-release` finishes, so the workflow first
345
+ waits (up to 15 minutes) until that exact version installs. It then builds the site against
346
+ it, and the build fails if a different version was installed.
347
+
348
+ One-time setup by a repository admin:
349
+
350
+ 1. Create an Amplify app with no connected repository and a `main` branch. Add a rewrite
351
+ that sends every path that is not a file to `/index.html` as a 200:
352
+ `</^[^.]+$|\.(?!(css|js|svg|woff2|png|ico|json|txt|map)$)([^.]+$)/>`. Without it,
353
+ opening `/usage` directly returns 404. If the site must not be public, turn on access
354
+ control for the branch.
355
+ 2. The workflow connects the way Cloudwick's other UI repos do, through the
356
+ `.github/actions/aws-profile-setup` action: GitHub's OIDC provider assumes the sandbox
357
+ role (`SANDBOX_OIDC_ROLE_ARN` in `SANDBOX_REGION`), and that session chains into a CI/CD
358
+ role in the account that hosts the Amplify app. Make sure the `SANDBOX_REGION` and
359
+ `SANDBOX_OIDC_ROLE_ARN` secrets are available to this repository, and that the sandbox
360
+ role trusts it.
361
+ 3. In the Amplify account, use a CI/CD role the sandbox role may assume, allowed to call
362
+ `amplify:CreateDeployment`, `amplify:StartDeployment` and `amplify:GetJob` on the app.
363
+ 4. Store the Amplify app ID as the `AMPLIFY_APP_ID` variable, that role's ARN as the
364
+ `AMPLIFY_ROLE_ARN` variable and the app's region as the `AMPLIFY_REGION` variable.
365
+
261
366
  ### Versioning
262
367
 
263
368
  The sync script classifies every icon by Figma node id and derives the release from what
@@ -269,6 +374,17 @@ public export.
269
374
  | Icon renamed or removed | `major` |
270
375
  | New icons | `minor` |
271
376
  | Artwork redrawn | `patch` |
377
+ | Category or component description changed in Figma | `patch` |
272
378
 
273
379
  Renaming a layer in Figma to fix a typo is a breaking change for every consumer. Layer
274
380
  names are a public contract.
381
+
382
+ The manifest's keywords also come from [`src/keywords.json`](src/keywords.json), which is
383
+ edited by hand in an ordinary pull request. `groups` are synonym sets: an icon whose slug
384
+ or Figma description contains any member, as a whole word, gets every member. `icons`
385
+ adds terms to one icon by slug; a slug that is no longer published is reported by the
386
+ build and ignored. Commit keyword changes as `fix(keywords): ...` so they release as a
387
+ patch; `chore` and `docs` commits publish nothing, and the edit would never ship.
388
+
389
+ The shape of the public `manifest.json` is a public API too: a new field is a `feat`, and removing or
390
+ redefining one is breaking and bumps its `schemaVersion`.
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export * from './components/index.js';
2
2
  export { type IIconProps, type TIconSize, iconSizePx } from './props.js';
3
3
  export { createIcon, type TSvgIcon, type TSvgIconProps } from './createIcon.js';
4
+ export type { IIconManifest, IIconManifestEntry, TIconVariant } from './manifest-types.js';
@@ -0,0 +1,33 @@
1
+ import type { TIconName } from './components/registry.js';
2
+ /** How an icon is drawn, from its slug's suffix when the other style also exists. */
3
+ export type TIconVariant = 'filled' | 'outline';
4
+ /** One icon in `@cloudwick/icons/manifest.json`. */
5
+ export interface IIconManifestEntry {
6
+ /** SVG filename without `.svg`, e.g. `3d-rotate-filled`. */
7
+ slug: string;
8
+ /** The export, e.g. `Icon3dRotateFilled`. */
9
+ component: TIconName;
10
+ /** Deep-import specifier, e.g. `@cloudwick/icons/Icon3dRotateFilled`. */
11
+ import: string;
12
+ /** Raw SVG specifier, e.g. `@cloudwick/icons/svg/3d-rotate-filled.svg`. */
13
+ svg: string;
14
+ /** Figma category, e.g. `Arrows (Round)`; `Uncategorized` when there is none. */
15
+ category: string;
16
+ /** `null` unless both `<family>-filled` and `<family>-outline` are published. */
17
+ variant: TIconVariant | null;
18
+ /** The slug without its variant suffix: the filled and outline siblings share it. */
19
+ family: string;
20
+ /** Extra search terms beyond the slug's own words: synonyms and Figma descriptions. */
21
+ keywords: string[];
22
+ }
23
+ /** The shape of `@cloudwick/icons/manifest.json`. */
24
+ export interface IIconManifest {
25
+ /** Bumped when a field is removed or changes meaning. */
26
+ schemaVersion: 1;
27
+ package: '@cloudwick/icons';
28
+ count: number;
29
+ /** Every category in use, sorted. */
30
+ categories: string[];
31
+ /** Every icon, sorted by slug. */
32
+ icons: IIconManifestEntry[];
33
+ }
@@ -0,0 +1 @@
1
+ export {};