lism-mockup-guide

Lism Mockup Implementation Guide (@lism-css/mockup)

This is an implementation guide for creating screen mockups using Lism Mockup. Screen mockups are@lism-css/mockupのData directory(one screen = one file inpages/+ a small config file). The preview app (viewer) is bundled with the CLI, and no build configuration orpackage.jsonis needed on the mockup side. This skill only covers "what kind of files can be placed as a mockup (data contract)" and "the workflow from init to check".

Prerequisites (required): lism-css-guidemust be used together. This skilllism-css-guideIt is assumed that it has been installed at the same level. The way to write the markup itself — Primitive selection, token matching, Property Class, responsive design — should all followlism-css-guidethe implementation flow oflism-cli skill add. If it is not present, guide the user to add it with (installs all skills at once with no arguments). Do not write mockups based on guesswork alone without the guide.

Version information: This guide@lism-css/mockup@0.1.0Based on information as of.

Role division

• This skill: Data contract (file structure, schema, import rules) and the workflow of init → implementation → check → dev
• lism-css-guide: Everything about how to write markup. For execution level determination, pre-implementation checks, and pre-submission self-checks, follow the guide's procedures as-is (../lism-css-guide/SKILL.md）
• Authoritative source of the contract: lism-mockup initgenerated byREADME.md(contract description). If it conflicts with the summary in this skill, prioritize the generated artifact

Command

Command	Purpose
npx @lism-css/mockup init [dir]	Generation of template + contract description (first step)
npx @lism-css/mockup check [dir]	Non-interactive verification. Agents use this for self-checking
npx @lism-css/mockup dev [dir]	Start dev server (resident). For human browser checking

[dir]If omitted, the current directory. If installed locally, the bin namelism-mockupcan also be used to run it. Node requirement is^20.19.0 || >=22.12.0。

Workflow (strictly follow)

1. init: If the data directory does not yet exist, alwaysnpx @lism-css/mockup init <dir>start from. If the data directory already exists, do not run init and read the existing generated artifacts
   • If init conflicts with files it plans to generate, it exits non-zero without changes (existing files unrelated to the generation targets do not get in the way).--forceis an option that overwrites conflicting files, so do not use it without explicit instructions from the user
2. Contract confirmation: Always read the generatedREADME.md(contract description). Follow the structure of the sample page (pages/), and do not invent new structures
3. Implementation: pages/*.jsx|tsxWrite. From here onlism-css-guideFollow the implementation flow (execution level determination → pre-implementation check → implementation → pre-submission self-check)
4. Self-verification: npx @lism-css/mockup check <dir>Run.While check exits with a non-zero status, you must not report it as complete. Errors display the target file and cause, so fix them and re-run
5. Browser confirmation: The dev server is a resident process that does not terminate.Do not start it in the foreground and wait for it to terminate. Start it in the background, or have the user start it. Confirming appearance and render results is the user's role
6. Completion report: Report that check passed. Since check does not detect render-time errors (described later),devinclude a request for visual browser confirmation in the report

Data contract (summary)

Data directory structure:

mockup/
├── mockup.config.json      # 必須 — schemaVersion＋追加import＋表示メタデータ
├── tokens.json             # 任意 — デザイントークンの上書き
├── tokens.dark.json        # 任意 — ダーク時の値（initでは生成されない）
└── pages/                  # 必須 — 1ファイル=1画面（最低1ページ）
    ├── landing.jsx
    ├── components.jsx      # 予約ID — 共通部品の一覧（手で維持するページ）
    └── admin/
        ├── settings.jsx
        └── settings.css  # ページ付随CSS（settings.jsxが相対importする）

pages/

• 1 file = 1 screen.Default export a React component that takes no propsdo
• Page ID = pages/The relative path frompages/admin/settings.jsx → admin/settings). Subdirectories allowed
• Screens are automatically discovered from the file system.You only need to place the file; no registration in config is required
• .jsx / .tsxBoth can be used, butno type checking is performed(types are simply stripped). Same-named.jsxと.tsxcoexistence is an ID collision error
• useStateLocal UI state and event handlers such as these may be written.Do not write API communication, authentication, persistence, or business logic(a mockup is a picture of a screen, not an app)
• Page-associated CSS and images can be placed via relative import. In CSS, write only declarations that cannot be expressed with Property Class / Props, such as pseudo-elements, descendant selectors, and attribute states (judgment islism-css-guideのproperty-class.md）。c--*The CSS of@layer lism-customplaced inside

mockup.config.json (required)

{
  "schemaVersion": 2,
  "title": "Lism Mockup",
  "imports": ["lucide-react"],
  "pages": {
    "landing": { "label": "Landing", "category": "Marketing", "order": 10 }
  }
}

• schemaVersionis required and2
• titleis optional.importsis a package that additionally permits imports (described later).pagesonly overrides display metadata (label / category / order), and the default ordering is lexicographic by page ID
• componentsis a reserved page ID(described later). Since the viewer displays it fixed in the sidebar's "Viewer" group under the name "UI Parts", there is no need to write an entry here (label / category / orderare all ignored)
• Referencing a non-existent page ID is an error(a signal of forgotten deletion or a typo). Unknown top-level keys are also an error

tokens.json (optional)

lism.config-compatibletokensObjects (lism.config.jsのtokenssame as the form written in):

{
  "color": { "brand": "#2f6f5e", "success": "oklch(62% 0.14 152)" },
  "space": { "60": "calc(var(--s-unit) * 12)" }
}

• The top level is a token group that actually exists in Lism CSS (color / space / fz / bdrs / bxshonly, such as)
• New keys can be added only incoloronly. Other groups only override the values of existing keys
• Violations do not become warnings.checkとdevstartup exits with a non-zero code, anddevif it changes to a violation during monitoring after startup, errors are displayed in the terminal and browser while the server continues
• The decision of which tokens to use or override followslism-css-guideのtokens.mdfollows

Property Class is not generated for new keys in color. For examplecanvaseven if you add-bgc:canvassuch a class does not exist (even if written, there is no CSS). Use the color of a new key in one of the following ways:

<Group bgc="canvas">…</Group>   {/* props経由 → var(--canvas)に変換される */}

@layer lism-custom {
  .c--saveStatus::before { background-color: var(--success); }  /* CSS内はvar()直書き */
}

tokens.dark.json (optional)

A file that writes only the dark-mode values. Its format istokens.jsonthe same asthe presence or absence of the file = the presence or absence of dark mode support（initit is not generated, so create it yourself when needed).

• What can be written isonly overrides of tokens that the light side actually has as CSS variables. The basis is the merged light side (Lism defaults +tokens.jsonkeys added bytokens.jsonnot written incolor.base / color.textcan also be specified only in dark
• Adding new keys is not possible（colorexceptions are not applied to dark). Keys for which the light side has no actual value (bdrs.inner / flow.s / palette.keycoloretc.) also error. Howevertokens.jsonif an actual value is given in, it can be overridden
• There are no restrictions on groups (color / palette / space / fz / bxsh / varsetc. all). Violations aretokens.jsonthe same as, an error
• The value is output inside the.set--darkclass (:root.set--darkis not).whether the whole page or part of it,className="set--dark"only inside the box with
• @media (prefers-color-scheme: dark)is not output. If you need OS setting following or a mode switching UI, prepare it on the page side
• vars（--Letc.) are overridden, the light-side tokens that reference them (palette.* / space.* / fz.*etc.) are also automatically redeclared into the same.set--darkblock (var()is resolved by the element that declared it)

import rules

Bare imports are only allowed for packages on the allowlist. The following standard packages can always be used without configuration and are resolved from the CLI-side node_modules (there is no need to add dependencies to the user project).

Package	Example
react / react-dom	import { useState } from 'react'
lism-css	import { Stack, Group } from 'lism-css/react'
@lism-css/ui	import { Button } from '@lism-css/ui/react/Button'

Other packages aremockup.config.jsonのimportsにonly the package namewritten to allow ("lucide-react"is allowed,"lucide-react/icons"is not allowed).

• Declared packages are installed on the project side, including the data directory. If not installed, it stops before bundle
• lucide-reactis provided by the CLI, so installation is not required.importsIt is necessary to write it in (initis included from the beginning in the configuration generated by). What can be used is named imports from the root, such as icons (Bell / BellIcon / Sidebaretc.) andIcon / createLucideIcononly.icons(record of all icons) andlucide-react/icons/bellsubpaths like are not provided (bothcheckmakes it an error)
• standard packages inimportswriting it in results in an error (because it is always allowed)
• devcreates the allowlist only once at startup.importsIf you editdevrestart
• @lism-css/uihas no root export. Always@lism-css/ui/react/<Component>import individually from
• Even within the allowlist, only paths that the package actually exports are allowed (nonexistent subpaths are rejected)
• Keep relative imports self-contained within the data directory, and the targets are.jsx / .tsx / .css / images (.png / .jpg / .jpeg / .gif / .svg / .webp) only
• absolute paths,/@fs/Path,../escaping outside the data directory via <code>, and bare imports that are not allowed all become errors as contract violations

Guarantee scope of check

checkはdevgoes through the same discovery, verification, and import rules as <code>, so the results of the two will not differ. It guarantees the following three points.

1. mockup.config.json / tokens.json / tokens.dark.jsonSchema of (schemaVersionincluding)
2. import boundaries (the rules above)
3. bundle success for all pages (reporting syntax errors, unresolved imports, and transformation errors with the target file and cause)

render is not executed. The following cannot be detected by check, and aredevleft to human browser confirmation in <code>:

• default export is not a React component
• Exceptions during the initial render, errors depending on browser APIs
• Whether the screen looks as intended

"check success" means "the mockup is well-formed and can be built," not "the screen is correct." Conversely,reporting a mockup whose check is failing as complete is prohibited.

Mockup-specific cautions

• Even for mockups targeting an Astro project, write them in React (.jsx / .tsx). The purpose of a mockup is "to be able to grasp the design and the classes and components that implement it," and it is not necessary to match import statements exactly with the real project
• The viewer has no color mode switching UI. Check dark mode withtokens.dark.json＋className="set--dark"and if a switching UI is needed, create it on the mockup's page side. If colors are written as tokens, both modes can be checked as is (avoiding hardcoded colors islism-css-guideas per the normal rules)
• The viewer's default display is the gallery. Reserved IDcomponentsEach page except <code> is arranged by category as iframe cards, and clicking a card opens that page in single view. The sidebar starts with the "Viewer" group (Design tokens → UI Parts → All pages), and below that pages by category are listed. "All pages" returns to the gallery. "Design tokens" automatically generates by the viewer a token list mergingtokens.jsonwith Lism defaults.tokens.dark.jsonIf <code> exists, immediately after the group whose values change in dark mode,color (dark)a section like <code> is added,.set--darkand it is rendered within the <code> scope. The sidebar page names always open in single view even while the gallery is displayed
• A list of common parts defined within the mockup cannot be automatically generated. ThereforeinitThe template of <code> containspages/components.jsx(A page that lines up the parts used in that mock, such as buttons, form components, badges, cards, etc.) is included. When a shared component is added, it should also be listed on this page.componentsis the reserved ID; the viewer displays it with the fixed name "UI Parts" in the "Viewer" group, and excludes it from the category-based list and gallery. If the list is unnecessary, you may delete the entire file (if you give it a different name, it will be treated as an ordinary screen)
• The page is just JSX (arbitrary code execution) with no sandbox. Only run mockups you trust

How to update this skill file itself

If the user requests a skill update,lism-cli skill addorlism-cli skill updateplease guide them. If you want to check for the latest version, check the GitHub repository'sskills/lism-mockup-guideplease check.