@snacky/ui 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+How `@snacky/ui` got to its current state. The README documents what the
+package *is*; this documents how it got there, including the mistakes, so the
+verification claims in the README can be taken at face value.
+
+## Icon set replaced with the real Figma artwork (0.3.0)
+
+The package originally shipped a hand-drawn "starter" icon set: roughly 30
+generic 24x24 glyphs with a 1.5px stroke, written from memory and explicitly
+documented as not pixel-faithful to Figma.
+
+That was replaced by all 42 Outline + 10 Solid icons exported from Figma's own
+`Icon-outline` (node `55:2062`) and `Icon-solid` (`8772:5851`) component sets.
+Two structural surprises came out of it:
+
+- The icons are **filled outline shapes**, not stroked paths. The weight is
+  baked into each shape, so there is no `strokeWidth` to set.
+- The set is **not uniform**. Icons are authored at 16, 20 or 24 units
+  depending on where they are used, so each carries its own viewBox instead of
+  being scaled from a single size.
+
+Three icons are named for what they actually draw rather than their Figma
+property value, confirmed by rendering the exported geometry: Figma's `cod` is
+a delivery truck (`truck`), `list` is a right chevron (`chevronRight`), and the
+two `password` states are a crossed-out and an open eye (`eyeOff` / `eye`).
+
+`src/icons/outline.tsx` and `solid.tsx` are now generated from
+`assets/icons/icons.json` by `scripts/generate-icons.js`, the same source that
+generates the Compose package's `SnackyIcons.kt`, so the two platforms cannot
+drift apart. Parity was verified by diffing every path, viewBox and fill-rule
+in both generated outputs against the source: 52/52 exact on each side.
+
+### Attribution gap (0.3.0 and 0.3.1, both unpublished)
+
+Those two versions shipped the Flaticon artwork with no attribution at all,
+inside an MIT package. CC BY 4.0 permits the redistribution but requires the
+credit to travel with the work. Both versions were unpublished from npm and
+0.3.2 shipped the attribution embedded in the generated icon sources (using
+`/*!` so minifiers keep it), verified to survive the bundler into
+`dist/index.js`, plus a `NOTICE` file in the published tarball.
+
+## Component verification pass
+
+The first pass of every component was built from `components.json`'s spec
+values and `code.tsx` samples alone. Those are real token values, but
+`code.tsx` is an *illustrative* usage sample, not the site's actual rendered
+implementation - and that first pass was never checked against how the site
+really renders each component.
+
+Real mismatches slipped through as a result: Button's icon slot, Toggle's true
+dimensions, Checkbox's checkmark color, Radio's dot size, Tab's gap,
+ProductCard's cart-button size, and List's status colors, among others.
+
+Every component was then diffed against `index.html`'s own `PG[id].impl`
+strings - the React-createElement code that powers the site's Live Preview
+panels - field by field: padding, colors, font, line-height, and
+hover/pressed/disabled states. That implementation is treated as authoritative
+where `components.json`'s prose spec disagrees with it.
+
+`List` and `Header` were additionally cross-checked directly against their
+Figma component sets, and both agreed with the verified implementation.
+
+`BottomSheet` and `Section` have not had this treatment yet.
+
+## Other fixes worth recording
+
+- **ProductImage sizing (0.3.1).** The component builds its class name as
+  `--${usage}`, but the stylesheet spelled the first two rules `--card` and
+  `--details` instead of `--product-card` and `--product-details`. Those two
+  usages - the 128px card image and the 200px detail image, the two most common
+  ones - matched no rule at all and rendered completely unsized.
+- **Unstyled-components trap (0.3.3).** The README's usage snippet said
+  `import '@snacky/ui'` would pull in the stylesheet "as a side effect". It does
+  not: tsup extracts the CSS to a standalone `dist/index.css` and never
+  re-injects it into the JS entry, so anyone following the snippet verbatim got
+  unstyled components. The correct import is `@snacky/ui/styles.css`.

package/README.md

@@ -15,7 +15,8 @@ npm install @snacky/ui
 ```
 
 Published at [npmjs.com/package/@snacky/ui](https://www.npmjs.com/package/@snacky/ui).
-To build from source instead (e.g. to work on the components themselves):
+To build from source instead (e.g. to work on the components themselves), clone
+[the repo](https://github.com/rezatresnas/snacky-design-system) and, from its root:
 
 ```bash
 cd packages/react-ui
@@ -26,7 +27,7 @@ npm run build
 ## Usage
 
 ```tsx
-import '@snacky/ui'; // pulls in theme/tokens.css as a side effect
+import '@snacky/ui/styles.css'; // required - the compiled bundle does not inject this for you
 import { Button, TextField, Checkbox } from '@snacky/ui';
 
 function SignupForm() {
@@ -58,49 +59,26 @@ Illustration, ProductImage, ProductCard.
 
 ## Verification status
 
-The first pass of every component was built from `components.json`'s `s`
-(spec) values and `code.tsx` samples alone - those are real token values, but
-`code.tsx` is an *illustrative* usage sample, not the site's actual rendered
-implementation. That first pass was **not** checked against how the site
-itself actually renders each component, and several real mismatches slipped
-through as a result (Button's icon slot, Toggle's true dimensions, Checkbox's
-checkmark color, Radio's dot size, Tab's gap, ProductCard's cart-button size,
-List's status colors, and more).
-
-Every component has since been diffed against `index.html`'s own `PG[id].impl`
-strings - the actual React-createElement code that powers the site's "Live
-Preview" panels, extracted and compared field-by-field (padding, colors,
-font, line-height, hover/pressed/disabled states) - and corrected to match.
-This is the authoritative source in this repo; `components.json`'s prose spec
-text occasionally disagrees with it (e.g. Checkbox's checkmark is documented
-as "white" but the verified implementation uses `#333333`) and the verified
-implementation wins in every such case.
-
-`List`'s `OrderListItem`/`NotificationListItem` were additionally cross-checked
-directly against their Figma component set (page "List", component `List`,
-`Property 1=order|notification` x `Property 2=<status>`) - the node tree
-(fills, strokes, padding, gap, type styles) matches the verified `PG.list.impl`
-implementation exactly, so both sources agree: 56x56 thumbnail frame (`#f4f4f5`
-background, not a token - a literal value distinct from any generated surface
-color), a per-status summary card (`itemsSummary` + bold `total`, a bordered
-COD chip on `processCod`, a `paymentDeadline` banner on `waiting`, a right-
-aligned primary Button - "Track Shipment" / "Buy Again" - on
-shipped/received/cancelled), and a title+message notification row with a
-`1px solid var(--border-main)` border on every state, not just unread.
-
-`Header` was added later, directly from Figma rather than retrofitted from
-an existing implementation: inspected the `Header` component set (page
-"Header", variants `Icon=Back|Close|None` x `Right Action=True|False`) node
-tree for exact spec values (16px/8px padding, 40x40px circular icon buttons,
-Poppins Bold 16px/36px title), verified against a live smoke-test render for
-all 4 variants (structure, computed styles, click handlers), and confirmed
-the `PG.header.impl` string added to the site itself matches the same spec.
-
-**One deliberate deviation, not an oversight:** `NavBar` items use `flex:1`
-to fill the container width, where the site's own demo hardcodes `72x72`
-per item - because that demo is only ever shown at a fixed 360px frame. A
-production nav bar needs to fill whatever width the real device is, so the
-flexible layout was kept on purpose.
+Every component is diffed against `index.html`'s own Live Preview
+implementation - the code that actually renders the documentation site - not
+just the spec values in `components.json`. Where the two disagree, the
+verified implementation wins. `List` and `Header` were additionally checked
+against their Figma component sets directly.
+
+Three things worth knowing before you rely on them:
+
+- **`NavBar` items use `flex: 1`** to fill the container, where the site's own
+  demo hardcodes `72x72` per item. That demo only ever renders at a fixed
+  360px frame; a real nav bar has to fill the actual device width, so this is
+  a deliberate deviation rather than a mismatch.
+- **`List`'s 56x56 thumbnail frame uses a literal `#f4f4f5`**, not a token -
+  it is a distinct value with no equivalent in the generated surface colors.
+- **`BottomSheet` and `Section`** have not been diffed field-by-field the way
+  the rest of the package has. Treat their exact padding and gap values as
+  reasonable-but-unverified.
+
+See [CHANGELOG.md](https://github.com/rezatresnas/snacky-design-system/blob/main/packages/react-ui/CHANGELOG.md)
+for how the package got here, including the mistakes.
 
 ## Artwork credit and licensing
 
@@ -133,14 +111,37 @@ what is already in the bundle.
   shape, there is no `strokeWidth` to set), and the set is **not uniform** -
   icons are authored at 16, 20 or 24px depending on use, so each carries its
   own viewBox and defaults to that natural size.
-- **Illustration** ships no artwork - pass your own hosted `src`.
+- **Illustration** ships no artwork - you supply the image. This is
+  deliberate and normal (Material, Radix and Chakra ship none either); the
+  component owns the documented canvas size for each variant, which is the
+  part that belongs in a design system. The Snacky artwork itself is modified
+  stock and is not ours to redistribute.
+
+  ```tsx
+  import { Illustration } from '@snacky/ui';
+
+  <Illustration variant="empty" src="/img/empty.svg" alt="No products found" />
+  ```
+
+  Variant sizes are fixed: `empty` 268x200, `createAccount` 360x240,
+  `welcome` 200x200, `success` 200x200, `discountReferral` 268x200. Export
+  your artwork at those ratios (SVG preferred) and host it wherever your app
+  already serves static assets.
+
+  **Where to get artwork that fits:** [Open Peeps](https://www.openpeeps.com/)
+  is CC0 (public domain - no attribution, no restrictions), so it is the
+  easiest drop-in. [unDraw](https://undraw.co/) needs no attribution and
+  allows commercial use, but its licence forbids redistributing the assets
+  "in packs", so use it in your own app rather than re-publishing it inside a
+  library of your own. Either way, check the licence yourself before shipping
+  - it is the one part of this that a component library cannot decide for you.
+
 - **Modal/Section**: the design system documents ~9 Modal "variants" and ~13
   Section "variants", but each is really the *same* shell component
   (`BottomSheet` / `Section`) with different `children` - so that's what's
   exported, matching every `code.tsx` sample exactly, rather than 22 near-
-  duplicate components. These two shells have not yet been diffed field-by-
-  field against `PG.modal`/`PG.section` the way the rest of the package has -
-  treat their exact padding/gap values as reasonable-but-unverified.
+  duplicate components. (See Verification status above for the caveat on
+  their exact padding/gap values.)
 
 ## Keeping this in sync