@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 +119 -3
- package/dist/index.d.ts +1 -0
- package/dist/manifest-types.d.ts +33 -0
- package/dist/manifest-types.js +1 -0
- package/manifest.json +4896 -0
- package/package.json +11 -3
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 {};
|