@deckdot/struq-icons 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `@deckdot/struq-icons` are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) on its own version line.
+
+## [Unreleased]
+
+## [1.0.0]
+
+The first release of Struq Icons: 182 icons in every form, browsable at https://struq.nl/iconen.
+
+The set started as the icon set Roy Heilbron drew for another product. It is the same drawing language (a 24 grid, a
+2 stroke at Lucide's weight and size, two tones, one hover motion per icon), rebranded to Struq and trimmed to the
+icons that make sense outside a support desk.
+
+### Added
+
+- 182 icons, drawn on a 24 grid with a 2 stroke and round caps:
+  - 118 icons, two-tone, each with its own hover motion;
+  - 14 status icons, one tone, coloured by the host;
+  - 50 glyphs, one tone, for small UI controls.
+- React components with types: one named export per icon in PascalCase, an `Icon` suffixed alias for each,
+  `StruqIconProps`, `ICON_CATALOG` and a deep import per icon (`@deckdot/struq-icons/icons/<name>`).
+- Colour props on every icon: `color` paints the shape and `accentColor` the accent. They set `--icon-base` and
+  `--icon-accent` inline, so one icon can take any colour without a stylesheet. No hooks, so icons stay Server
+  Components.
+- `StruqIconDraw`, the draw-in variant for empty states and heroes, as its own entry (`@deckdot/struq-icons/draw`).
+- `icons.css` (hover motion, reduced motion respected; the timing falls back to 200 ms on its own curve, so it runs
+  without any token file), `tokens.css` (the shape in the text colour, the accent in Struq's flame, `#e4572e` in light
+  and `#ff6b3d` in dark), `tokens-neutral.css` (one tone: every part follows `currentColor`) and `states.css` (one tone
+  at rest, the accent on hover, focus and the current control).
+- Two-tone SVGs with CSS variables, flat SVGs in Struq ink and flame for light and dark, and neutral SVGs in
+  `currentColor` for inline use.
+- `sprite.svg` with every icon as a `<symbol>`.
+- `iconify.json` (prefix `struq`) and `catalog.json` with Dutch and English search tags.
+- A Figma sheet with one 24 x 24 frame per icon, named by the icon, with the base and accent as separate layers, in
+  one group per category.
+
+### Renamed
+
+These kept their drawing and got a name that fits outside a support desk:
+
+- `sla-timer` is `timer`: a stopwatch is useful well beyond a service-level agreement.
+- `search-kb` is `file-search`: a page with a lens, which is what it shows. It moved to the files category.
+
+### Left out
+
+These were in the original set and are not in Struq Icons. Each one only means something on a support desk or in the
+original brand:
+
+- `plume`: the original product's logo mark. With it went the mark tier and the `accentSoftColor` prop that existed
+  only for its middle plume.
+- `ticket`, `escalate`, `urgent` and `queue`: support tickets and their escalation, priority and queue.
+- `call-transfer`, `hang-up`, `hold` and `voicemail`: call-centre telephony. `call`, `headset` and `mute` stay, they
+  are general.
+- `svr`: a form specific to the original product.
+- `internal-note`: a support-desk private note, a notebook with a padlock.
+
+The categories followed: `brand` is gone, and `support` became `work` (Werk en bellen).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roy Heilbron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,328 @@
-# Temporary Holding Version
+# Struq Icons
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@deckdot/struq-icons` is the icon set of [Struq](https://struq.nl). It has 182 icons in three tiers:
+
+| Tier | Count | What it is |
+|---|---|---|
+| icon | 118 | two-tone, each with its own hover motion |
+| status | 14 | one tone, coloured by the place it sits in |
+| glyph | 50 | one tone, for small controls such as chevrons and close |
+
+Every icon is drawn on a 24 grid with a 2 stroke and round caps, at Lucide's weight and size, so it drops in where
+Lucide was. The two tones are the set's identity: a base colour for the shape and an accent for the part that
+carries the meaning. At rest the accent can stay quiet and light up where you act; on hover each icon makes one small
+move that says what it does.
+
+The set ships in several forms. Pick the one that fits your work:
+
+- [React](#react) for web apps.
+- [CSS only](#css-only) for colours and motion on any page.
+- [Sprite](#sprite) for HTML without React.
+- [Plain SVG](#plain-svg) for documents, wikis and mail.
+- [Figma](#figma) for designers.
+- [Iconify](#iconify) for other frameworks.
+
+Browse, search and customise the whole set at [struq.nl/iconen](https://struq.nl/iconen).
+
+MIT licensed (see `LICENSE`): anyone can install and use it, no account or token needed.
+
+## Install
+
+```sh
+npm install @deckdot/struq-icons
+```
+
+React 18 or newer is a peer dependency. `motion` is only needed for the [draw-in variant](#draw-in).
+
+## React
+
+Import the stylesheets once, at the root of your app. Then import icons by name.
+
+```tsx
+import "@deckdot/struq-icons/tokens.css";
+import "@deckdot/struq-icons/icons.css";
+import { Search, Send } from "@deckdot/struq-icons";
+
+<button className="btn">
+  <Send size={20} />
+  Versturen
+</button>;
+```
+
+Every icon is a named export in PascalCase: `Search`, `FolderOpen`, `ChevronDown`. The barrel is tree-shakeable, so
+your bundle only holds the icons you import.
+
+### Props
+
+| Prop | Type | Default | What it does |
+|---|---|---|---|
+| `size` | `16`, `20`, `24`, `32` or `48` | `24` | width and height in px |
+| `strokeWidth` | number | `2` | the stroke width in grid units |
+| `label` | string | none | names the icon for screen readers |
+| `animate` | `"hover"`, `"draw"` or `"none"` | `"hover"` | the motion; `"none"` keeps the icon still |
+| `color` | any CSS colour | none | paints the shape, see [Colours](#colours) |
+| `accentColor` | any CSS colour | none | paints the accent |
+| `className` | string | none | merged with the icon's own class |
+
+Any other SVG prop passes through to the `<svg>`.
+
+An icon without a `label` is decoration. It gets `aria-hidden` and screen readers skip it. Give it a `label` when the
+icon is the only content, for example an icon button:
+
+```tsx
+<button type="button">
+  <Search label="Zoeken" />
+</button>
+```
+
+With a label the icon gets `role="img"` and a `<title>`.
+
+### Icon aliases
+
+Every icon also has an alias with an `Icon` suffix. Use it when a name clashes with something else in your file:
+
+```tsx
+import NextLink from "next/link";
+import { LinkIcon, ImageIcon, FileIcon, TextIcon } from "@deckdot/struq-icons";
+```
+
+`Link` clashes with `next/link`, `Image` with `next/image`, and `File` and `Text` with the DOM globals. `LinkIcon` is
+the same component as `Link`.
+
+### Deep imports
+
+Each icon also has its own entry, for tools that do not tree-shake:
+
+```tsx
+import { Search } from "@deckdot/struq-icons/icons/search";
+```
+
+The path uses the icon's file name in kebab case: `icons/chevron-down`, `icons/folder-open`.
+
+### The catalog
+
+`ICON_CATALOG` lists every icon with its name, tier and motion. Use it for pickers and settings screens:
+
+```tsx
+import { ICON_CATALOG } from "@deckdot/struq-icons";
+```
+
+The same data, plus categories and Dutch and English search tags, is in `@deckdot/struq-icons/catalog.json`.
+
+### Server Components
+
+The icons use no hooks and no client boundary. They render as React Server Components. Only the
+[draw-in entry](#draw-in) is a client component.
+
+## Colours
+
+Icons take their colours from CSS variables:
+
+| Variable | Paints | With `tokens.css` | Without |
+|---|---|---|---|
+| `--icon-base` | the shape | `currentColor` | `currentColor` |
+| `--icon-accent` | the part that carries the meaning | Struq flame, `#e4572e` (`#ff6b3d` in dark) | `currentColor` |
+| `--icon-accent-live` | the accent `states.css` shows where you act | Struq flame | `currentColor` |
+
+`tokens.css` gives the accent Struq's flame and keeps the shape in the text colour. Its dark values apply under a
+`.dark` class or a `[data-theme="dark"]` attribute, the two common dark-mode switches. Without it every part falls
+back to `currentColor`, so the icon follows the text colour.
+
+Set a variable on a parent to recolour a whole area:
+
+```css
+.sidebar {
+  --icon-base: var(--text-muted);
+  --icon-accent: var(--brand);
+}
+```
+
+Your own tokens work here too, so the icons follow your theme and dark mode.
+
+To colour one icon, use the colour props. They take any CSS colour, a hex value or a variable:
+
+```tsx
+<Search color="#1f2937" accentColor="#16a34a" />
+<Send color="var(--text)" accentColor="var(--brand)" />
+```
+
+`color` paints the shape and `accentColor` the accent. Leave one out and that part keeps its variable. The props set
+the variables inline on the icon, so they win over a parent's variables. No hooks are involved, so icons stay Server
+Components.
+
+To find your colours, open [struq.nl/iconen](https://struq.nl/iconen): pick a line and an accent colour and every
+icon follows. It gives you the props and the CSS to copy, and the SVG and PNG files in those colours.
+
+To paint the accent in the base colour, put `data-icon-accent="off"` on a parent. This needs `icons.css`:
+
+```tsx
+<nav data-icon-accent="off">
+  <Search />
+</nav>
+```
+
+Status icons have one tone. Set their colour with `color` on the place they sit in, for example your warning colour on
+a warning row.
+
+### One tone at rest, the accent where you act
+
+`states.css` is the rule Struq uses in its own interfaces: at rest every icon is one tone, so a screen full of icons
+stays calm, and the accent lights up on the hovered or focused control, a highlighted menu item, and the control that
+is current, selected, pressed, checked or open. Import it after the tokens:
+
+```tsx
+import "@deckdot/struq-icons/tokens.css";
+import "@deckdot/struq-icons/icons.css";
+import "@deckdot/struq-icons/states.css";
+```
+
+It works on any `a`, `button`, menu item, tab, option, switch, tree item, row or `li`, with nothing per component.
+Put `data-icons="live"` on an area that should show the set as drawn, accent always on. A colour prop still wins.
+
+### Neutral theme
+
+For one tone everywhere, import `tokens-neutral.css` instead of `tokens.css`. Every part follows `currentColor`, in
+light and dark alike.
+
+```tsx
+import "@deckdot/struq-icons/tokens-neutral.css";
+import "@deckdot/struq-icons/icons.css";
+```
+
+## Motion
+
+`icons.css` gives every icon of tier icon its own short motion. An icon is still at rest. It moves only:
+
+- when the pointer is on the icon, or on the link, button, menu item, tab or option that holds it (or any element with
+  the class `group`);
+- when that host has keyboard focus.
+
+Nothing moves on load, on a timer or in a loop. A disabled host never moves its icon. Status icons and glyphs have no
+motion.
+
+Reduced motion is respected for you. When the user's system asks for reduced motion, no icon moves. You do not need
+to write anything for it.
+
+To keep one icon still, pass `animate="none"`. To tune the feel, set `--duration-icon` (default `200ms`) or
+`--ease-icon` (default `cubic-bezier(0.2, 0.8, 0.2, 1)`) on a parent.
+
+## Draw-in
+
+`StruqIconDraw` draws an icon in once when it mounts. It is meant for empty states, first runs and a hero. It lives in
+its own entry, so the main import never pulls in `motion`.
+
+```sh
+npm install motion
+```
+
+```tsx
+import { Inbox } from "@deckdot/struq-icons";
+import { StruqIconDraw } from "@deckdot/struq-icons/draw";
+
+<StruqIconDraw icon={Inbox} size={48} delay={0.2} />;
+```
+
+| Prop | What it does |
+|---|---|
+| `icon` | the icon component to draw |
+| `delay` | seconds before the drawing starts; only the first value counts |
+
+It takes every other icon prop too. It draws once and never loops; give it a new `key` to draw it again. A drawn icon
+has no hover motion. Under reduced motion, without JavaScript and on the server, it shows the finished icon at once. It
+is a client component.
+
+## CSS only
+
+Any web page can use the stylesheets without React. Add them once:
+
+```css
+@import "@deckdot/struq-icons/tokens.css";
+@import "@deckdot/struq-icons/icons.css";
+```
+
+Paste the [two-tone SVG](#plain-svg) of an icon inline in your HTML. It gets its colours from the variables. The hover
+motion needs `class="sqi"`, `data-animate="hover"` and the `data-icon` attribute on the `<svg>`, the same as the React
+component renders.
+
+## Sprite
+
+`sprite.svg` holds every icon as a `<symbol>` with the icon's name as its id. Copy it to your site's public files:
+
+```sh
+cp node_modules/@deckdot/struq-icons/dist/sprite.svg public/
+```
+
+Then use an icon by name:
+
+```html
+<svg width="24" height="24" aria-hidden="true">
+  <use href="/sprite.svg#search" />
+</svg>
+```
+
+The sprite stays two-tone through `--icon-base` and `--icon-accent`. It has no hover motion.
+
+## Plain SVG
+
+Every icon ships as a single SVG file, in four versions:
+
+| Path | Colours | Use it for |
+|---|---|---|
+| `svg/<name>.svg` | the CSS variables, falling back to `currentColor` | inline in HTML |
+| `svg/light/<name>.svg` | Struq ink and flame baked in, for light backgrounds | `<img>`, documents, wikis, mail |
+| `svg/dark/<name>.svg` | Struq ink and flame baked in, for dark backgrounds | the same, on dark |
+| `svg/neutral/<name>.svg` | `currentColor` for every part, one tone | inline, in the text colour |
+
+From the package:
+
+```tsx
+import searchSvg from "@deckdot/struq-icons/svg/light/search.svg";
+```
+
+Whether that import gives a URL or the SVG text depends on your bundler. Without a bundler, take the files from
+`node_modules/@deckdot/struq-icons/dist/svg/`, or straight from a CDN:
+`https://cdn.jsdelivr.net/npm/@deckdot/struq-icons/dist/svg/light/search.svg`.
+
+An `<img>` cannot read the page's CSS variables or its text colour, so the neutral file has nothing to follow there.
+Use the light or dark file in an `<img>` and in documents.
+
+For slides, the showcase at [struq.nl/iconen](https://struq.nl/iconen) downloads any icon as a 512 px PNG, in your
+colours if you picked any.
+
+## Figma
+
+`dist/figma/struq-icons.svg` holds every icon as its own 24 x 24 frame named by the icon, in the light colours. Drag
+the file onto a Figma page. Inside a frame the layers are `search-base` and `search-accent` (`-badge` where an icon
+has one). The frames sit in one group per category, named like `actions-icons`, and the caption under each frame is a
+separate text layer.
+
+To turn the frames into components:
+
+1. In the layers panel, select the frames of a category, without the captions.
+2. Choose Create multiple components. Each frame becomes a component with the frame's name.
+3. To file the components in a folder per category, rename the selection to `actions/$&` (with that category's name)
+   with Ctrl R or Cmd R. `$&` keeps the current name.
+
+## Iconify
+
+`@deckdot/struq-icons/iconify.json` is the set in Iconify's JSON format, with the prefix `struq`. Iconify's plugins
+and loaders for Vue, Svelte, Astro and Tailwind read it, so `struq:search` works there. The Iconify bodies carry the
+light colours.
+
+## Versioning
+
+The package follows semantic versioning on its own version line.
+
+| Change | Bump |
+|---|---|
+| a new icon | minor |
+| a redraw that keeps the meaning | minor, called out in the changelog |
+| a fix nobody would see | patch |
+| a rename or a removal | major |
+
+After a rename, the old name stays as an alias for one major version. `CHANGELOG.md` lists the new, redrawn and
+renamed icons of every version.
+
+## Licence
+
+MIT, copyright Roy Heilbron. See `LICENSE`.

package/dist/catalog.d.ts

@@ -0,0 +1,9 @@
+import type { ReactElement } from "react";
+import type { StruqIconProps } from "./struq-icon.js";
+export interface IconCatalogEntry {
+    name: string;
+    component: (props: StruqIconProps) => ReactElement;
+    tier: "icon" | "status" | "glyph";
+    motion: string | null;
+}
+export declare const ICON_CATALOG: readonly IconCatalogEntry[];