pixelize-design-library 2.4.2-beta.50 → 2.4.2-beta.51

package/CHANGELOG.md

@@ -7,6 +7,10 @@ Versions follow semver. The `beta` dist-tag is released manually from the active
 `^2.4.2-beta.43`) — a caret range on a prerelease is satisfied by the next stable publish, which
 silently downgrades you.
 
+Found a bug or a gap? Report it as a GitHub issue and track it to closure — see
+[COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md#found-a-gap-or-a-bug-report-it-then-track-it). A fix's
+line below names its issue number.
+
 ## [Unreleased] — 2.4.2-beta.x
 
 The theme-tokens/dark-mode line. Still in beta; the breaking items below land together in the

package/COMPONENT-GOTCHAS.md

@@ -11,6 +11,52 @@ so it's available without checking out the library's source repo. Its companion
 
 ---
 
+## Found a gap or a bug? Report it, then track it
+
+The library exists so a UI change is made **once, here** — not patched per app. So when a component
+is wrong, missing a prop, or can't express what a screen needs, **don't work around it in your app
+and move on.** Report it upstream; a workaround nobody knows about is a bug that gets rediscovered
+in every other app.
+
+**What counts:** a component that renders wrong (misaligned, clipped, wrong size or colour, off the
+control scale), a prop you need that doesn't exist, a silent-failure trap that isn't listed below, or
+a doc that contradicts what you measured.
+
+**How to report** — one GitHub issue on `pixelize-tech/Micro-Components`, with the label `bug` or
+`enhancement`. From a terminal (AI agents included) this is one command:
+
+```bash
+gh issue create --repo pixelize-tech/Micro-Components --label bug \
+  --title "[consumer] <Component>: <what is wrong>" \
+  --body "Version: <output of: npm ls pixelize-design-library>
+App / screen: <where you saw it>
+Expected: <what should happen>
+Actual: <what happens, with measured numbers if it is visual>
+Repro: <props / minimal snippet>
+Workaround in the app: <none, or what you did and where, so it can be removed>"
+```
+
+Measure, don't eyeball: for a visual bug give the rendered size and offset (`getBoundingClientRect`)
+and the `size` prop — "icon 1.5px above centre at `sm`" gets fixed; "looks off" doesn't.
+
+**How it is tracked** — the issue is the record; there is no second list.
+
+| State | What it means | What you do |
+| --- | --- | --- |
+| Open | Reported, not yet fixed | Keep any workaround, and comment its file path on the issue |
+| Closed with a version | Fixed in the named beta/release, and the fix is under `### Fixed` in [CHANGELOG.md](CHANGELOG.md) citing the issue | Bump the pin to that version (exact, never a caret on a prerelease), **delete the workaround**, close your own follow-up |
+| Closed as `wontfix` / `invalid` / `duplicate` | Not changing, or already covered | Read the reason; the workaround stays, or use the issue it points to |
+
+Before reporting, search first — `gh issue list --repo pixelize-tech/Micro-Components --search "<component>" --state all`
+— and check the [CHANGELOG.md](CHANGELOG.md) shipped with your installed version; the gap may already
+be fixed in a newer beta.
+
+**Maintainers:** a fix closes its issue in the same change that lands it, and its CHANGELOG line
+names the issue number and the version that ships it. A workaround someone left in an app is only
+removable if the issue says which version fixes it, so never close without naming one.
+
+---
+
 ## A colour rung flips direction between light and dark
 
 `colors.primary[700]` is a deep purple in light mode and a **pale** lavender in dark. The scales are

package/DESIGN-GUIDE.md

@@ -192,6 +192,10 @@ hides its primary; when only one section is empty on a populated page, that sect
 - Centered page titles, hero-sized headings, `size="lg"` buttons, or `size` props restating the default.
 - More than one solid button in a view; a destructive action without `AlertDialog`.
 - A page with only the data state.
+- **Work around a library gap silently.** If a component is wrong or can't do what the screen
+  needs, report it (see "Found a gap or a bug?" in [COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md)) so
+  it is fixed once, here, and remove your workaround when the issue closes.
+
 
 ## 9. Reference pages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelize-design-library",
-  "version": "2.4.2-beta.50",
+  "version": "2.4.2-beta.51",
   "description": "React component library for Pixelize apps: themeable Chakra-based components, design tokens and light/dark brand theming.",
   "keywords": [
     "react",