justskill-design 0.0.1 → 3.2.0

package/package.json

@@ -1,10 +1,72 @@
 {
   "name": "justskill-design",
-  "version": "0.0.1",
-  "description": "Name reserved for justSkill — design web pages as a validated HTML file with inline CSS. The skill lives at https://github.com/justskill-ai/justskill-design",
+  "version": "3.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Design web pages as a validated HTML file with inline CSS. Agent edits by CLI, human edits on a local canvas, both write the same file. Also ships a DeepSeek Harness plugin.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/justskill-ai/justskill-design.git" },
-  "homepage": "https://github.com/justskill-ai/justskill-design",
-  "keywords": ["justskill", "design", "html", "css", "canvas", "agent-skills", "claude-code"],
-  "publishConfig": { "access": "public" }
+  "main": "./dsh/index.js",
+  "exports": {
+    ".": "./dsh/index.js",
+    "./client": "./dsh/client.js",
+    "./design.mjs": "./design.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "justskill": "design.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "design.mjs",
+    "lib",
+    "canvas",
+    "references",
+    "scripts/install.mjs",
+    "dsh",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "README.en.md",
+    "docs/dsh-workbench.png"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "keywords": [
+    "justskill",
+    "design",
+    "html",
+    "css",
+    "canvas",
+    "agent-skills",
+    "claude-code",
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "skill"
+  ],
+  "engines": {
+    "node": ">=18",
+    "dsh": ">=0.2.1-rc.3 <0.3.0-0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "references": "node scripts/gen-references.mjs",
+    "references:check": "node scripts/gen-references.mjs --check",
+    "images:check": "node scripts/check-images.mjs",
+    "install:skill": "node scripts/install.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justskill-ai/justskill-design.git"
+  },
+  "homepage": "https://github.com/justskill-ai/justskill-design#readme",
+  "bugs": {
+    "url": "https://github.com/justskill-ai/justskill-design/issues"
+  }
 }

package/references/cookbook.md

@@ -0,0 +1,156 @@
+# Cookbook
+
+<!-- Generated by scripts/gen-references.mjs from lib/table.mjs. Do not edit. -->
+
+The patterns that come up on every page, written the way this format wants them.
+
+## Page shell
+
+```html
+<section data-id="home" data-type="page" data-name="Home" data-canvas="0,0" style="width:390px;height:844px">
+  <div data-id="home__root" data-type="frame" style="display:flex;flex-direction:column;width:100%;height:100%;background-color:var(--color-bg)">
+  </div>
+</section>
+```
+
+The page owns its own size. The root fills it.
+
+## A vertical stack with spacing
+
+```html
+<div data-id="home__list" data-type="frame" style="display:flex;flex-direction:column;gap:12px;padding:24px">
+</div>
+```
+
+`gap` is the whole spacing system. There is no `margin`.
+
+## A row that pushes its ends apart
+
+```html
+<div data-id="home__bar" data-type="frame" style="display:flex;align-items:center;justify-content:space-between;height:48px;padding:0 16px;background-color:#ffffff">
+</div>
+```
+
+## Two children that split the width
+
+```html
+<div data-id="home__split" data-type="frame" style="display:flex;flex-direction:row;gap:8px">
+  <div data-id="home__left" data-type="frame" style="flex:1 1 0%;min-width:0"></div>
+  <div data-id="home__right" data-type="frame" style="flex:1 1 0%;min-width:0"></div>
+</div>
+```
+
+`flex:1 1 0%` plus `min-width:0` is the one spelled way to fill a row. Without
+`min-width:0`, a long word pushes the child past its share.
+
+## A card
+
+```html
+<div data-id="home__card" data-type="frame" style="display:flex;flex-direction:column;gap:8px;padding:16px;background-color:#ffffff;border:1px solid #e5e7eb;border-radius:12px;box-shadow:0 1px 2px #00000014">
+</div>
+```
+
+## A tilted card
+
+```html
+<div data-id="home__card" data-type="frame" style="transform:rotate(-1.5deg);display:flex;flex-direction:column;gap:8px;padding:16px;background-color:#ffffff;border-radius:16px;box-shadow:0 1px 2px #0000000a, 0 16px 34px -12px #00000014"></div>
+```
+
+`rotate()` turns the element about its own centre and changes no layout: its
+neighbours stay put, and the canvas drags and resizes it along its turned
+axes. `translate()` and `scale()` are refused — they are `left`/`top` and
+`width`/`height` written a second time. A page cannot be rotated; tilt the
+cards on it.
+
+## Text sizes
+
+| Role | Style |
+|---|---|
+| Display | `font-size:44px;font-weight:700;line-height:1.1` |
+| Title | `font-size:24px;font-weight:600;line-height:1.25` |
+| Body | `font-size:16px;font-weight:400;line-height:1.5` |
+| Label | `font-size:14px;font-weight:500;line-height:1.4` |
+| Caption | `font-size:12px;font-weight:400;line-height:1.4;color:#6b7280` |
+
+## A pill
+
+```html
+<p data-id="home__tag" data-type="text" style="font-size:12px;font-weight:500;padding:4px 10px;background-color:#f3f4f6;border-radius:9999px;color:#374151">New</p>
+```
+
+`border-radius:9999px` is the pill. A circle is `border-radius:50%` on a square box.
+
+## An image that fills its box
+
+```html
+<img data-id="home__photo" data-type="image" src="photo.jpg" alt="A room" style="width:100%;height:200px;object-fit:cover;border-radius:12px">
+```
+
+`alt` is required. `alt=""` marks a decorative image, and that is different from
+omitting it.
+
+## A photo when the user gave none
+
+Take the `src` from `references/images.md`, and write its `alt` and credit with it:
+
+```html
+<img data-id="home__photo" data-type="image" src="https://images.unsplash.com/photo-1543988884-c01cfa7b41c2?w=1080&amp;q=80&amp;fm=jpg" alt="Turquoise water meeting a white sand beach" data-credit="Photo by Harry Holder on Unsplash" style="width:100%;height:220px;object-fit:cover;border-radius:12px">
+```
+
+`data-credit` names the photographer. It never renders, and the Licence does not
+require it: keeping it costs one attribute and makes the source of a photo findable
+later.
+
+## A background image
+
+```html
+<div data-id="home__hero" data-type="frame" style="height:240px;background-image:url(&quot;hero.jpg&quot;);background-size:cover;background-position:center"></div>
+```
+
+## A gradient scrim
+
+```html
+<div data-id="home__scrim" data-type="frame" style="height:120px;background-image:linear-gradient(180deg,#ffffff00,#00000099)"></div>
+```
+
+A linear gradient's opaque stops are read by the contrast checker. A radial
+gradient is accepted as a value, but the checker cannot see through it, so text
+over a radial gradient is judged against the surface below it.
+
+## A dot grid
+
+```html
+<div data-id="home__dots" data-type="frame" style="width:100%;height:100%;background-image:radial-gradient(circle, #e3e3e3 1px, #00000000 1.5px);background-size:26px 26px"></div>
+```
+
+`background-size` takes a pair, so a repeatable texture is a value, not an
+asset: the gradient draws one dot, and the size tiles it. The image repeats by
+default, so no `background-repeat` is needed or available.
+
+## Glass behind a floating bar
+
+```html
+<div data-id="home__bar" data-type="frame" style="position:absolute;left:16px;top:16px;padding:8px 12px;background-color:#ffffffb8;border:1px solid #ffffffcc;border-radius:999px;backdrop-filter:blur(20px) saturate(1.4)"></div>
+```
+
+`blur()` and `saturate()` only, in that order. The surface colour stays
+translucent: the filter blurs what is behind the element, it does not supply a
+background of its own. A renderer that ignores the filter still draws the
+translucent fill, which is why the fill is written too.
+
+## The most common refusals
+
+| Written | Refused because | Write this |
+|---|---|---|
+| `animation` | No animation. A design file is a still. | remove it |
+| `border-bottom` | Use border-width with four values for one edge. | `border-width: 0 0 1px 0` |
+| `border-left` | Use border-width with four values for one edge. | `border-width: 0 0 0 1px` |
+| `border-right` | Use border-width with four values for one edge. | `border-width: 0 1px 0 0` |
+| `border-top` | Use border-width with four values for one edge. | `border-width: 1px 0 0 0` |
+| `cursor` | The format describes appearance, not interaction. A cursor is behavior. | remove it |
+| `font` | Write the longhand properties. | `font-family, font-size, font-weight and line-height` |
+| `grid-gap` | The property is named gap. | `gap` |
+| `grid-template-columns` | The format has no grid. Flex covers the same layouts. | `display:flex with flex:1 on the children` |
+| `grid-template-rows` | The format has no grid. Flex covers the same layouts. | `display:flex with flex:1 on the children` |
+| `margin-bottom` | Write the shorthand: margin: 0 0 8px 0. | `gap on the parent, or margin on this element` |
+| `margin-left` | Write the shorthand: margin: 0 0 0 8px. | `gap on the parent, or margin on this element` |

package/references/images.md

@@ -0,0 +1,171 @@
+# Image catalogue
+
+Unsplash photographs for a page that needs a picture and has not been told which
+one to use. Grouped by what the page is looking for; every URL was requested from
+`images.unsplash.com` and returned a 200 on 2026-10-25.
+
+<!-- Hand-written data, not generated. scripts/check-images.mjs re-checks the URLs. -->
+
+## How to use it
+
+- **The user's image wins.** A URL, a file or a `.pen` image the user supplied is never
+  replaced. This catalogue is for the case where nobody said which picture to use.
+- **Choose by subject, not by the nearest row.** A hero wants a wide landscape, a
+  feature card an object, an avatar a face, a testimonial one person.
+- **Copy the `src` whole.** `?w=1080&q=80&fm=jpg` is part of the URL that was verified.
+  The `&` needs no escaping in the fragment you hand to `add`; the file is written with
+  `&amp;`.
+- **A small avatar may ask for less:** change `w=1080` to `w=400` and leave the rest
+  of the URL alone.
+- **The credit goes in `data-credit`.** It never renders. The Licence does not require
+  it; keeping it makes a photo findable again the day the URL breaks.
+- **No photo fits?** A solid colour or a linear gradient is the honest placeholder.
+  Never invent a `photo-…` id: a URL that resolves to nothing renders an empty box,
+  which is worse than a placeholder nobody mistakes for a photograph.
+
+## Landscapes and scenery
+
+Wide and tall scenes for heroes, cards and full-bleed backgrounds.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1634879036244-18870f8b804f?w=1080&q=80&fm=jpg` | Green meadow below snow-capped peaks at golden hour | Photo by Greg Š on Unsplash |
+| `https://images.unsplash.com/photo-1542273917363-3b1817f69a2d?w=1080&q=80&fm=jpg` | Dense pine forest in thick morning fog | Photo by Marita Kavelashvili on Unsplash |
+| `https://images.unsplash.com/photo-1696190288876-a2b40fcc63a9?w=1080&q=80&fm=jpg` | Dead tree stumps standing in a calm forest lake | Photo by Brett Mayson on Unsplash |
+| `https://images.unsplash.com/photo-1638732984528-f255c9714619?w=1080&q=80&fm=jpg` | Smooth desert dunes fading into haze | Photo by raouf bedrani on Unsplash |
+| `https://images.unsplash.com/photo-1570290887796-27624be22a60?w=1080&q=80&fm=jpg` | Waterfall pouring over dark basalt cliffs | Photo by Ben Eaton on Unsplash |
+| `https://images.unsplash.com/photo-1685466695371-9fa8510634d0?w=1080&q=80&fm=jpg` | Pink poppies in bloom under a clear blue sky | Photo by Steve DiMatteo on Unsplash |
+| `https://images.unsplash.com/photo-1491838592561-ab572ec2d2cb?w=1080&q=80&fm=jpg` | Sunbeams breaking through a misty forest | Photo by Mel on Unsplash |
+| `https://images.unsplash.com/photo-1612441822281-778c7b2d4f38?w=1080&q=80&fm=jpg` | Golden sunrise over layered mountain ridges | Photo by Simon Lohmann on Unsplash |
+| `https://images.unsplash.com/photo-1543988884-c01cfa7b41c2?w=1080&q=80&fm=jpg` | Turquoise water meeting a white sand beach, from above | Photo by Harry Holder on Unsplash |
+| `https://images.unsplash.com/photo-1504596274545-5c136d4338f2?w=1080&q=80&fm=jpg` | Steep mountains flanking a deep blue fjord | Photo by Rod Long on Unsplash |
+| `https://images.unsplash.com/photo-1726486061288-783c5cad8090?w=1080&q=80&fm=jpg` | Autumn trees around a still lake under grey sky | Photo by Linda Christiansen on Unsplash |
+| `https://images.unsplash.com/photo-1665073526612-a2c3d7faddca?w=1080&q=80&fm=jpg` | Sunlit road curving through tall pine trees | Photo by Photos of Korea on Unsplash |
+
+## Portraits and faces
+
+One person, face readable at small sizes. Good for avatars, authors and a testimonial's photo.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=1080&q=80&fm=jpg` | Laughing woman in a red turtleneck, dark wavy hair | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=1080&q=80&fm=jpg` | Woman with slicked-back hair under blue studio light | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1524504388940-b1c1722653e1?w=1080&q=80&fm=jpg` | Woman with long blonde hair on a grey studio backdrop | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1554151228-14d9def656e4?w=1080&q=80&fm=jpg` | Freckled young woman with a braided bun, hand on chin | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=1080&q=80&fm=jpg` | Young woman with a red bob by a lake | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=1080&q=80&fm=jpg` | Man in a grey sweater, studio headshot | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1506794778202-cad84cf45f1d?w=1080&q=80&fm=jpg` | Bearded man in a grey knit sweater on black | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=1080&q=80&fm=jpg` | Smiling bearded man in a white t-shirt | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=1080&q=80&fm=jpg` | Man with grey hair and glasses in a green polo | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1560250097-0b93528c311a?w=1080&q=80&fm=jpg` | Man in glasses and a navy blazer by a window | Photo from Unsplash |
+
+## Groups and people at work
+
+More than one person: teams, friends, hands. For about sections, culture pages and testimonials.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1522071820081-009f0129c71c?w=1080&q=80&fm=jpg` | Team working on laptops at a long wooden table | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1521737604893-d14cc237f11d?w=1080&q=80&fm=jpg` | Group with headphones collaborating around a table | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1543269865-cbf427effbad?w=1080&q=80&fm=jpg` | Four young people talking around a cafe table | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1522202176988-66273c2fd55f?w=1080&q=80&fm=jpg` | Three young women laughing over laptops | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1495474472287-4d71bcdd2085?w=1080&q=80&fm=jpg` | Four hands toasting with coffee cups | Photo from Unsplash |
+
+## Interiors and workspaces
+
+Rooms and desks without a face: offices, a restaurant, a working setup.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1497366216548-37526070297c?w=1080&q=80&fm=jpg` | Modern empty office corridor with glass partitions | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1517248135467-4c7edcad34c4?w=1080&q=80&fm=jpg` | Restaurant interior with dark wood tables and pendant lights | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1498050108023-c5249f4df085?w=1080&q=80&fm=jpg` | Programmer desk with an open laptop, code and coffee | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1517336714731-489689fd1ca8?w=1080&q=80&fm=jpg` | Half-open laptop lit with purple and orange neon | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1504384308090-c894fdcc538d?w=1080&q=80&fm=jpg` | Busy open-plan office with rows of people at laptops | Photo from Unsplash |
+
+## Objects and food
+
+A single product or plate on a quiet background: good for cards, features and lists.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1505740420928-5e560c06d30e?w=1080&q=80&fm=jpg` | Black over-ear headphones on a bright yellow background | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1526170375885-4d8ecf77b99f?w=1080&q=80&fm=jpg` | White instant camera on a plain white surface | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1542291026-7eec264c27ff?w=1080&q=80&fm=jpg` | Red running shoe on a matching red background | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1523275335684-37898b6baf30?w=1080&q=80&fm=jpg` | Two smartwatches with blank round faces on white | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1512621776951-a57141f2eefd?w=1080&q=80&fm=jpg` | Colourful salad bowl with avocado, tomatoes and chickpeas | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1567620905732-2d1ec7ab7445?w=1080&q=80&fm=jpg` | Pancake stack with syrup poured from a small cup | Photo from Unsplash |
+
+## Sport, hobbies and daily life
+
+Exercise, shopping, music, study and a cafe: for fitness, retail, education and
+lifestyle pages.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1517836357463-d25dfeac3438?w=1080&q=80&fm=jpg` | Man deadlifting a barbell in a dark gym | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1571019613454-1cb2f99b2d8b?w=1080&q=80&fm=jpg` | Woman doing sit-ups on a mat by a bright window | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1476480862126-209bfaa8edc8?w=1080&q=80&fm=jpg` | Runner's legs climbing weathered concrete steps | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1483985988355-763728e1935b?w=1080&q=80&fm=jpg` | Woman in sunglasses carrying shopping bags outside | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1445205170230-053b83016050?w=1080&q=80&fm=jpg` | Clothing racks full of coats in a boutique | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1554118811-1e0d58224f24?w=1080&q=80&fm=jpg` | Customers and a barista inside a plant-filled cafe | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1511671782779-c97d3d27a1d4?w=1080&q=80&fm=jpg` | Vintage silver microphone against coloured blurred lights | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1503676260728-1c00da094a0b?w=1080&q=80&fm=jpg` | Stack of books, a red apple and alphabet blocks | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1416879595882-3373a0480b5b?w=1080&q=80&fm=jpg` | Gardening flat lay with a soil scoop and spilled potting mix | Photo from Unsplash |
+
+## Cities and buildings
+
+Streets, skylines and a house at dusk: for travel, real estate and city pages.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1449824913935-59a10b8d2000?w=1080&q=80&fm=jpg` | New York avenue with skyscrapers and yellow taxis | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1477959858617-67f85cf4f1df?w=1080&q=80&fm=jpg` | Aerial Chicago skyline at dusk beside the lake | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1519501025264-65ba15a82390?w=1080&q=80&fm=jpg` | Wet New York street with cars at dusk between towers | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1494526585095-c41746248156?w=1080&q=80&fm=jpg` | Modern house exterior at dusk with a warm lit entrance | Photo from Unsplash |
+
+## Textures and backgrounds
+
+No subject to recognise: gradients, ink and water for a back layer behind text.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=1080&q=80&fm=jpg` | Abstract purple to pink gradient | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1557682224-5b8590cd9ec5?w=1080&q=80&fm=jpg` | Abstract blue to orange-red gradient | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1541701494587-cb58502866ab?w=1080&q=80&fm=jpg` | Blue and orange ink swirling in dark water | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1674005619701-285543ad3a40?w=1080&q=80&fm=jpg` | Calm blue water surface with soft ripples | Photo by Ch Photography on Unsplash |
+
+## Animals
+
+For pets, farming and anything that wants a friendly non-human.
+
+| src | Shows | Credit |
+|---|---|---|
+| `https://images.unsplash.com/photo-1750363890360-2fc2f5136187?w=1080&q=80&fm=jpg` | Brown cow grazing in a lush green meadow | Photo by Seval Torun on Unsplash |
+| `https://images.unsplash.com/photo-1514888286974-6c03e2ca1dba?w=1080&q=80&fm=jpg` | Black and white cat resting on a wooden railing | Photo from Unsplash |
+| `https://images.unsplash.com/photo-1543466835-00a7907e9de1?w=1080&q=80&fm=jpg` | Beagle looking up with its tongue out | Photo from Unsplash |
+
+## Licence
+
+The photos come from [Unsplash](https://unsplash.com) under the
+[Unsplash License](https://unsplash.com/license): free to download, copy, modify and
+use, including commercially, without permission and without attribution. Three things
+that licence does not cover, and that matter to a design:
+
+- **Reselling or compiling.** You cannot sell unmodified copies, and you cannot build a
+  competing photo service out of them. A design, a mockup and a shipped page are fine.
+- **Unsplash+.** Its paid photos are a different licence. None are in this file.
+- **People and trademarks.** The faces above belong to real people with rights of
+  publicity; the object photos may show a brand. A stock face in an avatar or a mockup
+  is ordinary use. A shipped page that presents one as a real customer's testimonial,
+  or a logo as your product, is not covered by the photo licence.
+
+The images are **hotlinked**, never copied into the repository: the design file stays
+text, and the photos render only while there is a connection. A photo its author
+deletes stops resolving, so run `npm run images:check` before a release that depends
+on them; it prints every URL that no longer resolves.
+
+A credit reads `Photo by <name> on Unsplash` when the photographer's name was recorded
+(the photos inherited from `examples/miniprogram.pen`), and `Photo from Unsplash` when
+it was not. The licence does not require attribution, so either one is a complete
+credit; the first is simply easier to trace.