@snacky/ui 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# 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` were checked later, while porting them to the
+Compose package, and both turned up real bugs: `BottomSheet` defaulted to
+showing a drag handle that none of the nine documented Figma variants actually
+have (the prop was inverted to `showHandle`, defaulting to `false`), and
+`Section`'s "see more" chevron was using the wrong color. That check also
+established that their spacing is variant-dependent by design rather than
+unverified - see the README's Verification status.
+
+## 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

@@ -59,49 +59,30 @@ 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`, `Header`, `BottomSheet` and `Section`
+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` spacing is variant-dependent by design.** Both
+  shells have since been checked against Figma, and the finding was that no
+  single shell default reproduces every variant: BottomSheet's block gap is
+  32px on Welcome, 24px on Calendar and 16px elsewhere, and Section's "Variant"
+  layout has no horizontal shell padding at all, with its header owning the
+  24px instead. The shells ship sensible defaults and expect `children` to
+  override the spacing where a specific composition needs to.
+
+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
 
@@ -163,9 +144,8 @@ what is already in the bundle.
   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 on why their spacing is
+  variant-dependent.)
 
 ## Keeping this in sync
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snacky/ui",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Snacky App design system - React component library. Generated from the source-of-truth design system at ../../index.html (tokens.json / components.json), pixel-accurate to Figma.",
   "license": "MIT",
   "author": "rezatresnas",
@@ -34,7 +34,8 @@
   },
   "files": [
     "dist",
-    "NOTICE"
+    "NOTICE",
+    "CHANGELOG.md"
   ],
   "sideEffects": [
     "**/*.css"