twiddle-panel 0.0.0-stage → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravi
+
+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,62 @@
-# Temporary Holding Version
+# Panel by Twiddle
 
-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.
+A design-system tweak panel you drop into any prototype. Designers expose a few
+intentional knobs (type, colour, shape, density, depth); anyone reviewing the
+prototype can explore them live and share the exact version as a link.
+
+**Step-by-step guide with copy-ready snippets and agent prompts: [panel.twiddle.in](https://panel.twiddle.in)**
+
+## Install
+
+Panel is a design tool: load it in development or in shared prototype links, not in a production site.
+
+Panel used to be published as `@theoldpixel/twiddle`; that package is deprecated in favour of `twiddle-panel`.
+
+**Projects with a build tool (Vite, Next.js…)**
+
+```bash
+npm install -D twiddle-panel
+```
+
+```js
+// in your app's entry file
+import 'twiddle-panel';
+```
+
+That's all: the panel adds the token defaults itself (first in `<head>`, so
+your own CSS still wins). To load the panel only while developing, keep the
+tokens in every build and import the panel in development:
+
+```js
+import 'twiddle-panel/tokens.css';
+if (import.meta.env.DEV) import('twiddle-panel');
+```
+
+**Plain HTML prototypes** (no install needed)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/twiddle-panel@0.6.0/dist/twiddle.js" defer></script>
+```
+
+The prototype's CSS must use the `--twd-*` token variables
+(for example `border-radius: var(--twd-radius-control)`). Hard-coded values
+won't respond to the panel.
+
+Optional layout roles (token contract v0.2) name what a space is for:
+`--twd-page-pad`, `--twd-section-gap`, `--twd-card-pad`, `--twd-card-gap` and
+`--twd-control-gap`. Each points at a spacing step by default, so prototypes
+that use them can be re-pointed in **Edit every token › Spacing › Roles**.
+
+## Using the panel
+
+- The **Simple** page tweaks the whole page with broad knobs: the **Character** pad (drag up/down for spacing, left/right for shadow strength), then Fonts, Brand, Neutral, Mode and Corners (buttons and cards together). **Edit every token** opens a page per area (Fonts, Type scale, Colours, Spacing, Corners, Borders, Shadows): the area's knobs, then each of its tokens as a row you can set to a fixed value. An edited token shows **Custom** and its own reset, and stays put when you change the broad knobs. **Spacing › Roles** points each layout role (page padding, section gap, card padding, card gap, control gap, control padding) at another spacing step or a fixed value. **Copy link** shares the exact version (`?twd=…`).
+- **Pick** (crosshair) selects one element. The panel then shows only the sections that element uses. Choose **This element** or **All `.class` (n)** to set where the tweaks go. Add `data-twd="name"` to an element to control what counts as "all like this".
+- **Compare** (half circle): hold it, or press Alt+C, to see the original page.
+- **Undo / Redo** in the footer, or ⌘Z / ⇧⌘Z while the panel has focus. Reset can be undone too.
+- **Changes** lists every tweak with the token values before and after. Use × to remove one.
+- **Copy prompt** turns the tweaks into a Markdown prompt for a coding agent, so they become permanent in the source. Use the arrow next to it to choose between *Preview before copying* and *Copy without preview*.
+- Colour pairs that fall below WCAG AA show a warning in Colour, in Changes and in the prompt.
+
+## Licence
+
+MIT

package/dist/twiddle-tokens.css

@@ -0,0 +1,71 @@
+/* ==========================================================
+   Panel token contract — v0.2
+   Default values for every role token. Prototypes use ONLY
+   these variables; the panel overrides them live.
+   ========================================================== */
+
+:root {
+  /* ---------- Typography ---------- */
+  --twd-font-heading: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --twd-font-body: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+
+  /* Balanced scale (1.2) from a 16px base */
+  --twd-text-xs: 0.694rem;
+  --twd-text-sm: 0.833rem;
+  --twd-text-base: 1rem;
+  --twd-text-lg: 1.2rem;
+  --twd-text-xl: 1.44rem;
+  --twd-text-2xl: 1.728rem;
+  --twd-text-3xl: 2.074rem;
+
+  --twd-leading-tight: 1.2;
+  --twd-leading-normal: 1.5;
+
+  /* ---------- Colour (roles) ---------- */
+  --twd-bg: #fafafa;
+  --twd-surface: #ffffff;
+  --twd-surface-raised: #ffffff;
+  --twd-text: #18181b;
+  --twd-text-muted: #71717a;
+  --twd-border: #e4e4e7;
+  --twd-primary: #4f46e5;
+  --twd-primary-hover: #4338ca;
+  --twd-on-primary: #ffffff;
+  --twd-focus: #6366f1;
+  --twd-success: #16a34a;
+  --twd-warning: #d97706;
+  --twd-danger: #dc2626;
+
+  /* ---------- Shape ---------- */
+  --twd-radius-control: 8px;
+  --twd-radius-container: 12px;
+
+  /* ---------- Density ---------- */
+  --twd-space-1: 4px;
+  --twd-space-2: 8px;
+  --twd-space-3: 12px;
+  --twd-space-4: 16px;
+  --twd-space-5: 24px;
+  --twd-space-6: 32px;
+  --twd-space-7: 48px;
+  --twd-space-8: 64px;
+  --twd-control-height: 40px;
+  --twd-control-pad-x: 16px;
+
+  /* ---------- Layout roles (v0.2) ----------
+     Optional. Each points at a spacing step, so Density still scales it,
+     and the panel's Edit › Spacing › Roles can point it at another step
+     or a fixed value. Use them where they fit; space-1…8 still work. */
+  --twd-page-pad: var(--twd-space-5);     /* side padding of the page */
+  --twd-section-gap: var(--twd-space-6);  /* between page sections */
+  --twd-card-pad: var(--twd-space-5);     /* inside cards, menus, modals */
+  --twd-card-gap: var(--twd-space-2);     /* between items in a card */
+  --twd-control-gap: var(--twd-space-3);  /* between buttons, chips, inputs in a row */
+
+  /* ---------- Depth ---------- */
+  --twd-border-width: 1px;
+  --twd-border-width-container: var(--twd-border-width); /* cards, menus */
+  --twd-shadow-sm: 0 1px 2px rgb(0 0 0 / 0.06);
+  --twd-shadow-md: 0 4px 12px rgb(0 0 0 / 0.08);
+  --twd-shadow-lg: 0 12px 32px rgb(0 0 0 / 0.12);
+}

package/dist/twiddle.d.ts

@@ -0,0 +1,34 @@
+/* Types for twiddle-panel. Importing the package mounts the panel (and adds the token defaults if the page doesn't load them). */
+
+/** Global settings per section, plus local tweaks per CSS selector under `scopes`. */
+export type TwiddleState = Record<string, unknown> & {
+  scopes?: Record<string, Record<string, Record<string, unknown>>>;
+};
+
+export interface TwiddleAPI {
+  /** Show the panel. */
+  open(): void;
+  /** Hide the panel. */
+  close(): void;
+  /** Show or hide the panel (also Alt/Option + T). */
+  toggle(): void;
+  /** Clear every setting and go back to the page's own defaults. */
+  reset(): void;
+  /** Undo / redo the last settings change. */
+  undo(): void;
+  redo(): void;
+  /** Start picking an element on the page to tweak on its own. */
+  pick(): void;
+  /** The Copy prompt text for the current tweaks (empty string if nothing changed). */
+  prompt(): string;
+  /** A copy of the current settings (what the ?twd= link carries). */
+  getState(): TwiddleState;
+}
+
+export declare const Twiddle: TwiddleAPI;
+
+declare global {
+  interface Window {
+    Twiddle: TwiddleAPI;
+  }
+}