@cherishxn/agent-scaffold 0.0.0-stage → 1.0.0

package/templates/next-fullstack-shadcn/web/src/design-widgets.css

@@ -0,0 +1,31 @@
+/* Generated by design:sync. Edit design/widgets.css. */
+/* These semantic hooks belong to the widget contract, never to a library. */
+[data-widget]{box-sizing:border-box!important;font-family:var(--design-typography-body-font-family)!important;letter-spacing:normal!important;text-transform:none!important;box-shadow:none!important}
+[data-widget="button"]{display:inline-flex!important;align-items:center!important;justify-content:center!important;gap:8px!important;vertical-align:middle!important;position:relative!important;min-width:0!important;height:var(--design-widgets-button-height)!important;min-height:var(--design-widgets-button-height)!important;padding:var(--design-widgets-button-padding-y) var(--design-widgets-button-padding-x)!important;margin:0!important;border:var(--design-widgets-button-border-width) solid transparent!important;border-radius:var(--design-widgets-button-radius)!important;font-size:var(--design-widgets-button-font-size)!important;font-weight:var(--design-widgets-button-font-weight)!important;line-height:var(--design-widgets-button-line-height)!important;cursor:pointer!important;text-align:center!important;white-space:nowrap!important;transition:background-color 180ms,border-color 180ms,color 180ms!important}
+[data-widget="button"] [data-part="label"]{display:inline!important;margin:0!important;padding:0!important;font:inherit!important;line-height:inherit!important;color:inherit!important}
+[data-widget="button"][data-variant="primary"]{background:var(--design-colors-primary)!important;color:var(--design-colors-primary-text)!important}
+[data-widget="button"][data-variant="primary"]:hover{background:var(--design-colors-primary-hover)!important}
+[data-widget="button"][data-variant="primary"]:active{background:var(--design-colors-primary-active)!important}
+[data-widget="button"][data-variant="secondary"]{background:var(--design-colors-control-background)!important;color:var(--design-colors-secondary-text)!important;border-color:var(--design-colors-secondary-border)!important}
+[data-widget="button"][data-variant="secondary"]:hover,[data-widget="button"][data-variant="secondary"]:active{background:var(--design-colors-secondary-hover)!important}
+[data-widget="button"][data-variant="danger"]{background:var(--design-colors-danger-background)!important;color:var(--design-colors-danger-text)!important;border-color:var(--design-colors-danger-border)!important}
+[data-widget="button"][data-variant="danger"]:hover,[data-widget="button"][data-variant="danger"]:active{background:var(--design-colors-danger-hover)!important}
+[data-widget="button"]:disabled{opacity:.5!important;cursor:not-allowed!important;pointer-events:none!important}
+[data-widget="input"],[data-widget="textarea"]{display:block!important;width:100%!important;min-width:0!important;margin:0!important;padding:var(--design-widgets-input-padding-y) var(--design-widgets-input-padding-x)!important;border:var(--design-widgets-input-border-width) solid var(--design-colors-control-border)!important;border-radius:var(--design-widgets-input-radius)!important;background:var(--design-colors-control-background)!important;color:var(--design-colors-text)!important;font-size:var(--design-widgets-input-font-size)!important;font-weight:400!important;line-height:var(--design-widgets-input-line-height)!important;outline:none!important;transition:border-color 180ms!important}
+[data-widget="input"]{height:var(--design-widgets-input-height)!important;min-height:var(--design-widgets-input-height)!important}
+[data-widget="textarea"]{padding:var(--design-widgets-textarea-padding-y) var(--design-widgets-textarea-padding-x)!important;border-width:var(--design-widgets-textarea-border-width)!important;border-radius:var(--design-widgets-textarea-radius)!important;font-size:var(--design-widgets-textarea-font-size)!important;line-height:var(--design-widgets-textarea-line-height)!important;resize:vertical!important;min-height:0!important}
+[data-widget="input"]::placeholder,[data-widget="textarea"]::placeholder{color:var(--design-colors-muted)!important;opacity:1!important}
+[data-widget="input"]:hover,[data-widget="textarea"]:hover{border-color:var(--design-colors-control-focus)!important}
+[data-widget="input"][aria-invalid="true"],[data-widget="textarea"][aria-invalid="true"]{border-color:var(--design-colors-error-border)!important}
+[data-widget="input"]:disabled,[data-widget="textarea"]:disabled{opacity:.5!important;cursor:not-allowed!important}
+[data-widget="button"]:focus-visible,[data-widget="input"]:focus,[data-widget="textarea"]:focus{outline:2px solid var(--design-colors-control-focus)!important;outline-offset:2px!important}
+[data-widget="alert"]{display:flex!important;align-items:flex-start!important;gap:var(--design-widgets-alert-gap)!important;margin:16px 0!important;padding:var(--design-widgets-alert-padding-y) var(--design-widgets-alert-padding-x)!important;border:var(--design-widgets-alert-border-width) solid var(--design-colors-error-border)!important;border-radius:var(--design-widgets-alert-radius)!important;background:var(--design-colors-error-background)!important;color:var(--design-colors-error-text)!important;font-size:var(--design-widgets-alert-font-size)!important;font-weight:400!important;line-height:var(--design-widgets-alert-line-height)!important}
+[data-widget="alert"][data-variant="success"]{background:var(--design-colors-success-background)!important;color:var(--design-colors-success-text)!important;border-color:var(--design-colors-success-border)!important}
+[data-widget="alert"] [data-part="icon"]{display:block!important;width:var(--design-widgets-alert-icon-size)!important;height:var(--design-widgets-alert-icon-size)!important;flex:none!important;margin:3px 0 0!important;color:inherit!important}
+[data-widget="alert"] [data-part="message"]{display:block!important;margin:0!important;padding:0!important;font:inherit!important;line-height:inherit!important;color:inherit!important;overflow-wrap:anywhere}
+[data-widget="badge"]{display:inline-flex!important;align-items:center!important;vertical-align:middle!important;white-space:nowrap!important;margin:0!important;padding:var(--design-widgets-badge-padding-y) var(--design-widgets-badge-padding-x)!important;border:var(--design-widgets-badge-border-width) solid var(--design-colors-badge-border)!important;border-radius:var(--design-widgets-badge-radius)!important;background:transparent!important;color:var(--design-colors-badge-text)!important;font-size:var(--design-widgets-badge-font-size)!important;font-weight:400!important;line-height:var(--design-widgets-badge-line-height)!important}
+[data-widget="panel"]{background:var(--design-colors-surface)!important;border:var(--design-widgets-panel-border-width) solid var(--design-colors-panel-border)!important;border-radius:var(--design-widgets-panel-radius)!important;padding:var(--design-widgets-panel-padding)!important;box-shadow:var(--design-effects-panel-shadow)!important}
+[data-widget="field"]{display:flex!important;flex-direction:column!important;gap:var(--design-widgets-field-gap)!important;margin:var(--design-widgets-field-margin-y) 0!important}
+[data-widget="field"]>[data-part="label"]{font-size:var(--design-widgets-field-font-size)!important;font-weight:var(--design-widgets-field-font-weight)!important;line-height:var(--design-widgets-field-line-height)!important}
+@media(max-width:760px){[data-widget="panel"]{padding:var(--design-spacing-s20)!important}}
+@media(prefers-reduced-motion:reduce){[data-widget]{transition-duration:0.01ms!important}}

package/templates/next-fullstack-shadcn/web/src/structure-view.tsx

@@ -0,0 +1,16 @@
+import {createElement,Fragment,type ReactNode} from 'react';
+import design from './design-runtime.json';
+import type {WidgetSet} from './widget-types';
+type Node={element:string;region:string;slot?:string;children?:Node[]};
+export function Structure({name,slots,widgets}:{widgets:WidgetSet;name:'root'|'checking'|'login'|'workspace';slots:Record<string,ReactNode>}) {
+ const {Panel}=widgets;
+ const node:Node=name==='root'?design.structure.root:design.structure.pages[name];
+ function render(item:Node):ReactNode {
+  const children=item.slot?slots[item.slot]:item.children?.map(render);
+  if(item.element==='slot')return <Fragment key={item.region}>{children}</Fragment>;
+  if(item.slot&&children==null)return null;
+  const props={className:item.region,'data-region':item.region,...(item.element==='a'?{href:'/'}:{})};
+  return item.element==='panel'?<Panel key={item.region} {...props}>{children}</Panel>:createElement(item.element,{key:item.region,...props},children);
+ }
+ return render(node);
+}

package/templates/next-fullstack-shadcn/web/src/styles.css

@@ -0,0 +1,3 @@
+@import "./design-tokens.css";
+@import "./design-layout.css";
+@import "./design-widgets.css";

package/templates/next-fullstack-shadcn/web/src/tailwind.css

@@ -0,0 +1,2 @@
+@import "tailwindcss/theme" layer(theme);
+@import "tailwindcss/utilities" layer(utilities);

package/templates/next-fullstack-shadcn/web/src/ui.tsx

@@ -0,0 +1,13 @@
+import type * as React from 'react';
+import {cva} from 'class-variance-authority';
+import {WidgetIcon} from './widget-icon';
+import type {AlertProps,ButtonProps,FieldProps,InputProps,PanelProps,TextAreaProps} from './widget-types';
+const button=cva('inline-flex items-center justify-center');
+export function Button({children,variant='primary',loading=false,disabled,className,type='button',...props}:ButtonProps){return <button {...props} type={type} data-widget="button" data-variant={variant} aria-busy={loading||undefined} disabled={disabled||loading} className={button({className})}><span data-part="label">{children}</span></button>;}
+export function Input({invalid,...props}:InputProps){return <input {...props} data-widget="input" aria-invalid={invalid||undefined}/>;}
+export function TextArea({invalid,...props}:TextAreaProps){return <textarea {...props} data-widget="textarea" aria-invalid={invalid||undefined}/>;}
+export function Panel({children,className='',...props}:PanelProps){return <section {...props} data-widget="panel" className={`panel ${className}`}>{children}</section>;}
+export function Field({children,label,htmlFor}:FieldProps){return <div data-widget="field" className="field"><label data-part="label" htmlFor={htmlFor}>{label}</label><div data-part="control">{children}</div></div>;}
+export function Alert({children,variant='error'}:AlertProps){return <div data-widget="alert" data-variant={variant} role={variant==='error'?'alert':'status'}><WidgetIcon kind={variant}/><div data-part="message">{children}</div></div>;}
+export function Badge({children}:{children:React.ReactNode}){return <span data-widget="badge" className="badge"><span data-part="label">{children}</span></span>;}
+export function Theme({children}:{children:React.ReactNode}){return <>{children}</>;}

package/templates/next-fullstack-shadcn/web/src/widget-icon.tsx

@@ -0,0 +1,5 @@
+import design from './design-runtime.json';
+export function WidgetIcon({kind}:{kind:'error'|'success'}) {
+ const icon=design.widgets.icons[kind];
+ return <svg data-part="icon" aria-hidden="true" viewBox={icon.viewBox} fill="none" stroke="currentColor" strokeWidth={icon.strokeWidth} strokeLinecap="round" strokeLinejoin="round">{icon.paths.map((path,index)=><path key={index} d={path}/>)}</svg>;
+}

package/templates/next-fullstack-shadcn/web/src/widget-types.ts

@@ -0,0 +1,13 @@
+import type * as React from 'react';
+export type ButtonProps=Omit<React.ButtonHTMLAttributes<HTMLButtonElement>,'color'>&{variant?:'primary'|'secondary'|'danger';loading?:boolean};
+export type InputProps=Omit<React.InputHTMLAttributes<HTMLInputElement>,'size'>&{invalid?:boolean};
+export type TextAreaProps=React.TextareaHTMLAttributes<HTMLTextAreaElement>&{invalid?:boolean};
+export type AlertProps={children:React.ReactNode;variant?:'error'|'success'};
+export type PanelProps=React.HTMLAttributes<HTMLElement>;
+export type FieldProps={children:React.ReactNode;label:string;htmlFor:string};
+
+export type WidgetSet={
+ Button:React.ComponentType<ButtonProps>;Input:React.ComponentType<InputProps>;TextArea:React.ComponentType<TextAreaProps>;
+ Alert:React.ComponentType<AlertProps>;Panel:React.ComponentType<PanelProps>;Field:React.ComponentType<FieldProps>;
+ Badge:React.ComponentType<{children:React.ReactNode}>;Theme:React.ComponentType<{children:React.ReactNode}>;
+};

package/templates/next-fullstack-shadcn/web/src/workspace-model.ts

@@ -0,0 +1,85 @@
+export type User={id:string;email:string};
+export type RecordItem={id:string;title:string;content:string;created_at:string;updated_at:string};
+export type RecordPage={items:RecordItem[];total:number;page:number;pageSize:number};
+export type WorkspaceState={user:User|null;checking:boolean;email:string;password:string;list:RecordPage;page:number;selected:string|null;title:string;content:string;editing:boolean;busy:boolean;loading:boolean;error:string;notice:string};
+const emptyList=():RecordPage=>({items:[],total:0,page:1,pageSize:10});
+export const initialWorkspaceState=():WorkspaceState=>({user:null,checking:true,email:'',password:'',list:emptyList(),page:1,selected:null,title:'',content:'',editing:false,busy:false,loading:false,error:'',notice:''});
+class StaleRequest extends Error {}
+class ApiError extends Error {constructor(message:string,public status:number){super(message);}}
+export function validateRecord(title:string,content:string):string {
+ const length=Array.from(title.trim()).length;
+ if(length<1||length>120)return '标题需为 1–120 个字符。';
+ if(Array.from(content).length>10000)return '正文最多 10,000 个字符。';
+ return '';
+}
+/** Framework-neutral business model. Views subscribe and forward user intent. */
+export function createWorkspaceModel(request:typeof fetch=fetch) {
+ let state=initialWorkspaceState(),token:string|null=null;
+ let identityEpoch=0,refreshSequence=0,busySequence=0,lifecycle=0;
+ const requests=new Set<AbortController>(),listeners=new Set<()=>void>();
+ const patch=(value:Partial<WorkspaceState>)=>{state={...state,...value};for(const listener of listeners)listener();};
+ function cancelRequests(){for(const controller of requests)controller.abort();requests.clear();}
+ function clearIdentity(){
+  identityEpoch++;refreshSequence++;busySequence++;cancelRequests();token=null;
+  patch({user:null,list:emptyList(),page:1,selected:null,title:'',content:'',editing:false,notice:'',error:'',password:'',busy:false,loading:false});
+ }
+ async function api<T>(path:string,method='GET',body?:unknown):Promise<T> {
+  const epoch=identityEpoch,controller=new AbortController();requests.add(controller);
+  const timer=setTimeout(()=>controller.abort(),15000);
+  try{
+   const response=await request(`/api${path}`,{method,credentials:'same-origin',headers:{...(body===undefined?{}:{'Content-Type':'application/json'}),...(token?{Authorization:`Bearer ${token}`}:{})},...(body===undefined?{}:{body:JSON.stringify(body)}),signal:controller.signal});
+   if(epoch!==identityEpoch)throw new StaleRequest();
+   if(response.status===204)return undefined as T;
+   const data=await response.json();
+   if(epoch!==identityEpoch)throw new StaleRequest();
+   if(!response.ok){if(response.status===401)clearIdentity();throw new ApiError(data.error?.message||'请求失败，请检查输入后重试。',response.status);}
+   return data as T;
+  }catch(error){
+   if(error instanceof ApiError||error instanceof StaleRequest)throw error;
+   if(epoch!==identityEpoch)throw new StaleRequest();
+   throw new Error('请求失败或超时，输入已保留。请先查看记录，确认结果后再操作。',{cause:error});
+  }finally{clearTimeout(timer);requests.delete(controller);}
+ }
+ const report=(error:unknown)=>{if(!(error instanceof StaleRequest))patch({error:(error as Error).message});};
+ function busy(){const sequence=++busySequence;patch({busy:true,error:''});return ()=>{if(sequence===busySequence)patch({busy:false});};}
+ async function refresh(){
+  const sequence=++refreshSequence;patch({loading:true});
+  try{const list=await api<RecordPage>(`/records?page=${state.page}&pageSize=10`);if(sequence===refreshSequence)patch({list});}
+  catch(error){if(sequence===refreshSequence)report(error);}
+  finally{if(sequence===refreshSequence)patch({loading:false});}
+ }
+ async function start(){
+  const current=++lifecycle;patch({checking:true});
+  try{const data=await api<{user:User}>('/auth/me');if(current===lifecycle){patch({user:data.user});await refresh();}}
+  catch(error){if(current===lifecycle&&!(error instanceof ApiError&&error.status===401))report(error);}
+  finally{if(current===lifecycle)patch({checking:false});}
+ }
+ function stop(){lifecycle++;identityEpoch++;refreshSequence++;busySequence++;cancelRequests();}
+ async function login(){
+  const done=busy();
+  try{const data=await api<{user:User;token?:string}>('/auth/login','POST',{email:state.email,password:state.password});clearIdentity();token=data.token??null;patch({user:data.user,password:'',notice:''});await refresh();}
+  catch(error){report(error);}finally{done();}
+ }
+ async function logout(){const done=busy();try{await api('/auth/logout','POST',{});clearIdentity();}catch(error){report(error);}finally{done();}}
+ function create(){patch({selected:null,title:'',content:'',editing:true,error:'',notice:''});}
+ async function open(id:string){
+  const done=busy();patch({notice:''});
+  try{const data=await api<RecordItem>(`/records/${id}`);patch({selected:data.id,title:data.title,content:data.content,editing:true});}
+  catch(error){report(error);}finally{done();}
+ }
+ async function save(){
+  const error=validateRecord(state.title,state.content);patch({error,notice:''});if(error)return;
+  const done=busy();
+  try{const data=await api<RecordItem>(state.selected?`/records/${state.selected}`:'/records',state.selected?'PUT':'POST',{title:state.title,content:state.content});patch({selected:data.id,title:data.title,content:data.content,notice:'已保存'});await refresh();}
+  catch(error){report(error);}finally{done();}
+ }
+ async function remove(confirmed:boolean){
+  if(!state.selected||!confirmed)return;
+  const done=busy();patch({notice:''});
+  try{await api(`/records/${state.selected}`,'DELETE');patch({editing:false,selected:null,title:'',content:'',notice:'已删除',...(state.page>1&&state.list.items.length===1?{page:state.page-1}:{})});await refresh();}
+  catch(error){report(error);}finally{done();}
+ }
+ async function changePage(page:number){if(page<1||!Number.isInteger(page))return;patch({page});await refresh();}
+ return {getSnapshot:()=>state,subscribe:(listener:()=>void)=>{listeners.add(listener);return ()=>{listeners.delete(listener);};},start,stop,login,logout,create,open,save,remove,changePage,setField:(field:'email'|'password'|'title'|'content',value:string)=>patch({[field]:value})};
+}
+export type WorkspaceModel=ReturnType<typeof createWorkspaceModel>;

package/templates/next-fullstack-shadcn/web/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": false,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/next-fullstack-shadcn/web/vitest.config.ts

@@ -0,0 +1,2 @@
+import {defineConfig} from 'vitest/config';
+export default defineConfig({test:{include:['lib/**/*.test.ts'],reporters:['default','junit'],outputFile:{junit:(process.env.SCAFFOLD_REPORT_DIR||'../reports')+'/native.xml'}}});

package/templates/react-fastapi-antd/.agents/skills/design-contract/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: design-contract
+description: Implement or change UI from this project's design contract, adapt its component library, and verify every declared widget state and page scenario. Use for UI implementation, design-token changes, library adaptation, or design drift.
+---
+
+Read root DESIGN.md, design/widgets.json, and design/structure.json before UI work. The shared design source is design/tokens.json plus the framework-neutral layout/widget styles and guide. Generated files are outputs, never the edit target.
+
+Keep these boundaries:
+- Design decisions belong in the design source only when the user requests a design change. A library default is not a reason to change the contract.
+- Widget anatomy, variants, states, geometry and icon paths belong in widgets.json. A new state needs a fixture; do not silently skip unsupported states.
+- Page regions and nesting belong in structure.json; framework views bind those slots to content.
+- Business state, validation and identity/request isolation belong in web/src/workspace-model.ts, which has no framework or component-library imports.
+- Library API names, DOM fixes and theme translation belong in web/src/ui.tsx. Use the canonical icon geometry; never silently substitute a similar library icon.
+
+After changes, run `npm run design:sync`, `npm run design:check`, then `npm run design:verify`. Run the affected business checks from README as well. Design verification starts a local, temporary fixture server, compares the selected adapter with the independent semantic HTML reference, and cleans its own fixture files. Dependencies and the Playwright Chromium browser must already be installed with the project's documented install command.
+
+The checker enumerates every variant/state in widgets.json and every page scenario in structure.json at every declared viewport. Position tolerance is 0.6 CSS px; computed colors, radii and SVG geometry must be identical. Keep browser, font availability, DPR, locale and content fixed. A screenshot is supporting evidence, not the pass criterion. Missing fixtures, TODOs, errors or incomplete coverage mean FAIL/NOT RUN, never PASS.
+
+For scaffold maintainers, root `npm run design:verify` regenerates and checks all eight stack/UI combinations and compares their actual measurements. A generated project's command covers its selected adapter against the reference; it does not claim that uninstalled libraries or other platforms were tested. A new framework needs its view binding; adding a library also requires dependency/lockfile registration, without changing design or business intent.
+
+When extracting a new website reference, inspect rendered desktop/mobile pages and computed styles. Separate observed values from approved adaptations. Record source limitations; do not infer exact values from screenshots or convert brand-specific content into a product requirement. Useful upstream approaches: [create-design-md](https://github.com/ibelick/ui-skills/blob/main/skills/create-design-md/SKILL.md) for evidence-based extraction and [Impeccable](https://github.com/pbakaus/impeccable) for targeted refinement. They are optional references, not runtime dependencies or authorization to install tools.
+
+Report the changed layer, exact commands, coverage and result.json path. Fix adapter deviations rather than weakening tolerances, dropping cases, accepting a new baseline, or changing the shared design to fit one library.

package/templates/react-fastapi-antd/.agents/skills/project-work/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: project-work
+description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+---
+
+Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
+
+For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.

package/templates/react-fastapi-antd/.claude/skills/design-contract/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: design-contract
+description: Implement or change UI from this project's design contract, adapt its component library, and verify every declared widget state and page scenario. Use for UI implementation, design-token changes, library adaptation, or design drift.
+---
+
+Read root DESIGN.md, design/widgets.json, and design/structure.json before UI work. The shared design source is design/tokens.json plus the framework-neutral layout/widget styles and guide. Generated files are outputs, never the edit target.
+
+Keep these boundaries:
+- Design decisions belong in the design source only when the user requests a design change. A library default is not a reason to change the contract.
+- Widget anatomy, variants, states, geometry and icon paths belong in widgets.json. A new state needs a fixture; do not silently skip unsupported states.
+- Page regions and nesting belong in structure.json; framework views bind those slots to content.
+- Business state, validation and identity/request isolation belong in web/src/workspace-model.ts, which has no framework or component-library imports.
+- Library API names, DOM fixes and theme translation belong in web/src/ui.tsx. Use the canonical icon geometry; never silently substitute a similar library icon.
+
+After changes, run `npm run design:sync`, `npm run design:check`, then `npm run design:verify`. Run the affected business checks from README as well. Design verification starts a local, temporary fixture server, compares the selected adapter with the independent semantic HTML reference, and cleans its own fixture files. Dependencies and the Playwright Chromium browser must already be installed with the project's documented install command.
+
+The checker enumerates every variant/state in widgets.json and every page scenario in structure.json at every declared viewport. Position tolerance is 0.6 CSS px; computed colors, radii and SVG geometry must be identical. Keep browser, font availability, DPR, locale and content fixed. A screenshot is supporting evidence, not the pass criterion. Missing fixtures, TODOs, errors or incomplete coverage mean FAIL/NOT RUN, never PASS.
+
+For scaffold maintainers, root `npm run design:verify` regenerates and checks all eight stack/UI combinations and compares their actual measurements. A generated project's command covers its selected adapter against the reference; it does not claim that uninstalled libraries or other platforms were tested. A new framework needs its view binding; adding a library also requires dependency/lockfile registration, without changing design or business intent.
+
+When extracting a new website reference, inspect rendered desktop/mobile pages and computed styles. Separate observed values from approved adaptations. Record source limitations; do not infer exact values from screenshots or convert brand-specific content into a product requirement. Useful upstream approaches: [create-design-md](https://github.com/ibelick/ui-skills/blob/main/skills/create-design-md/SKILL.md) for evidence-based extraction and [Impeccable](https://github.com/pbakaus/impeccable) for targeted refinement. They are optional references, not runtime dependencies or authorization to install tools.
+
+Report the changed layer, exact commands, coverage and result.json path. Fix adapter deviations rather than weakening tolerances, dropping cases, accepting a new baseline, or changing the shared design to fit one library.

package/templates/react-fastapi-antd/.claude/skills/project-work/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: project-work
+description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+---
+
+Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
+
+For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.

package/templates/react-fastapi-antd/.dockerignore

@@ -0,0 +1,18 @@
+**/node_modules
+**/.venv
+**/.next
+**/target
+**/dist
+**/__pycache__
+.git
+.env
+.env.*
+.scaffold-local-credentials
+.scaffold-runs
+reports
+
+**/test-results
+**/playwright-report
+**/.env
+**/.env.*
+!**/.env.example

package/templates/react-fastapi-antd/.env.example

@@ -0,0 +1,13 @@
+# Copy only for explicit local development. Never use production credentials in verify.
+APP_ORIGIN=http://localhost:5173
+PORT=8000
+WEB_PORT=5173
+POSTGRES_PORT=54329
+POSTGRES_USER=app
+POSTGRES_PASSWORD=replace-with-local-random-password
+POSTGRES_DB=app
+DATABASE_URL=postgresql://app:replace-with-local-random-password@localhost:54329/app
+AUTH_SECRET=replace-with-at-least-32-random-characters
+SEED_A_EMAIL=alice@example.test
+SEED_B_EMAIL=bob@example.test
+SEED_PASSWORD=replace-with-local-random-password

package/templates/react-fastapi-antd/.grok/skills/design-contract/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: design-contract
+description: Implement or change UI from this project's design contract, adapt its component library, and verify every declared widget state and page scenario. Use for UI implementation, design-token changes, library adaptation, or design drift.
+---
+
+Read root DESIGN.md, design/widgets.json, and design/structure.json before UI work. The shared design source is design/tokens.json plus the framework-neutral layout/widget styles and guide. Generated files are outputs, never the edit target.
+
+Keep these boundaries:
+- Design decisions belong in the design source only when the user requests a design change. A library default is not a reason to change the contract.
+- Widget anatomy, variants, states, geometry and icon paths belong in widgets.json. A new state needs a fixture; do not silently skip unsupported states.
+- Page regions and nesting belong in structure.json; framework views bind those slots to content.
+- Business state, validation and identity/request isolation belong in web/src/workspace-model.ts, which has no framework or component-library imports.
+- Library API names, DOM fixes and theme translation belong in web/src/ui.tsx. Use the canonical icon geometry; never silently substitute a similar library icon.
+
+After changes, run `npm run design:sync`, `npm run design:check`, then `npm run design:verify`. Run the affected business checks from README as well. Design verification starts a local, temporary fixture server, compares the selected adapter with the independent semantic HTML reference, and cleans its own fixture files. Dependencies and the Playwright Chromium browser must already be installed with the project's documented install command.
+
+The checker enumerates every variant/state in widgets.json and every page scenario in structure.json at every declared viewport. Position tolerance is 0.6 CSS px; computed colors, radii and SVG geometry must be identical. Keep browser, font availability, DPR, locale and content fixed. A screenshot is supporting evidence, not the pass criterion. Missing fixtures, TODOs, errors or incomplete coverage mean FAIL/NOT RUN, never PASS.
+
+For scaffold maintainers, root `npm run design:verify` regenerates and checks all eight stack/UI combinations and compares their actual measurements. A generated project's command covers its selected adapter against the reference; it does not claim that uninstalled libraries or other platforms were tested. A new framework needs its view binding; adding a library also requires dependency/lockfile registration, without changing design or business intent.
+
+When extracting a new website reference, inspect rendered desktop/mobile pages and computed styles. Separate observed values from approved adaptations. Record source limitations; do not infer exact values from screenshots or convert brand-specific content into a product requirement. Useful upstream approaches: [create-design-md](https://github.com/ibelick/ui-skills/blob/main/skills/create-design-md/SKILL.md) for evidence-based extraction and [Impeccable](https://github.com/pbakaus/impeccable) for targeted refinement. They are optional references, not runtime dependencies or authorization to install tools.
+
+Report the changed layer, exact commands, coverage and result.json path. Fix adapter deviations rather than weakening tolerances, dropping cases, accepting a new baseline, or changing the shared design to fit one library.

package/templates/react-fastapi-antd/.grok/skills/project-work/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: project-work
+description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+---
+
+Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
+
+For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.

package/templates/react-fastapi-antd/.scaffold-checks.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "template": "react-fastapi",
+  "ui": "antd",
+  "port": 5173,
+  "backend": true
+}

package/templates/react-fastapi-antd/AGENTS.md

@@ -0,0 +1,11 @@
+# 项目规则
+
+先读 README.md 的实际命令与 docs/PROJECT.md 的需求和架构。project.json 记录项目基本信息，个人记录是基础示例，简介不代表额外功能已经实现。
+
+按需求实现并运行相关检查：安装、启动、构建成功；登录和增删改查真实持久化；用户 A 无法访问用户 B 的记录。自查差异，允许合理更新测试，不以删除断言、跳过检查或关闭类型校验掩盖失败。交付实际文件、命令、结果，未运行明确说明。
+
+仅修改任务范围，保留其他改动。秘密只放本地环境，不提交或打印；模板 verify 使用隔离数据库。推送、发布和外部写入依任务授权执行。
+
+需要开发指引时使用 project-work Skill；未自动发现时按以上规则和 README 执行。
+
+修改 UI 前先读根目录 DESIGN.md。使用 design-contract Skill；设计源、同步命令和一致性检查以该文件为准。交付前运行 design:check 与 design:verify，报告实际覆盖范围。

package/templates/react-fastapi-antd/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/react-fastapi-antd/DESIGN.md

@@ -0,0 +1,208 @@
+---
+version: "alpha"
+name: "Scientific Workspace"
+description: "从 CleerScience 提炼的通用深色科技视觉，适配可读、安静的工具型界面。"
+colors:
+  primary: "#8fc3ff"
+  primary-hover: "#b5d8ff"
+  primary-active: "#69a9f3"
+  primary-text: "#02040a"
+  background: "#02040a"
+  text: "#f4f8ff"
+  surface: "#0b111d"
+  focus: "#8fc3ff"
+  border: "#283547"
+  brand: "#f4f8ff"
+  eyebrow: "#9baecb"
+  muted: "#a1afc3"
+  intro: "#b5c3d7"
+  panel-border: "#283547"
+  divider: "#202c3e"
+  record-text: "#f4f8ff"
+  record-meta: "#a1afc3"
+  record-hover: "#142237"
+  pagination-border: "#283547"
+  empty: "#a1afc3"
+  empty-heading: "#e2eeff"
+  success-background: "#102b25"
+  success-border: "#387c69"
+  success-text: "#a2e6cc"
+  error-background: "#311b24"
+  error-border: "#8f4c61"
+  error-text: "#ffbdcd"
+  footer-border: "#283547"
+  footer-text: "#a1afc3"
+  badge-border: "#435773"
+  badge-text: "#b5c3d7"
+  control-focus: "#8fc3ff"
+  control-border: "#657891"
+  control-background: "#080e18"
+  secondary-border: "#657891"
+  secondary-text: "#e2eeff"
+  secondary-hover: "#19283d"
+  danger-border: "#ad6578"
+  danger-background: "#311b24"
+  danger-text: "#ffbdcd"
+  danger-hover: "#472636"
+typography:
+  body:
+    fontFamily: "Inter,ui-sans-serif,-apple-system,BlinkMacSystemFont,\"Segoe UI\",\"PingFang SC\",\"Hiragino Sans GB\",\"Microsoft YaHei\",sans-serif"
+    fontSize: "16px"
+    lineHeight: 1.65
+  h1:
+    fontSize: "36px"
+    lineHeight: 1.2
+    letterSpacing: "-0.03em"
+    fontWeight: 560
+  login-heading:
+    fontSize: "48px"
+    lineHeight: 1.15
+    fontWeight: 560
+    letterSpacing: "-0.03em"
+  h2:
+    fontSize: "20px"
+    lineHeight: 1.4
+    fontWeight: 580
+    letterSpacing: "-0.02em"
+  h3:
+    fontSize: "18px"
+    fontWeight: 600
+    lineHeight: 1.5
+  label:
+    fontSize: "14px"
+    fontWeight: 600
+  eyebrow:
+    fontSize: "11px"
+    fontWeight: 700
+    letterSpacing: "0.22em"
+    lineHeight: 1.5
+  button:
+    fontSize: "14px"
+    fontWeight: 600
+    lineHeight: "20px"
+  caption:
+    fontSize: "12px"
+  intro:
+    fontSize: "18px"
+    lineHeight: 1.8
+  mobile-heading:
+    fontSize: "32px"
+    lineHeight: 1.2
+  mobile-page-heading:
+    fontSize: "28px"
+    lineHeight: 1.25
+rounded:
+  md: "0px"
+  panel: "0px"
+  full: "0px"
+spacing:
+  s0: "0px"
+  s1: "1px"
+  s2: "2px"
+  s3: "3px"
+  s4: "4px"
+  s6: "6px"
+  s8: "8px"
+  s10: "10px"
+  s12: "12px"
+  s14: "14px"
+  s15: "15px"
+  s16: "16px"
+  s18: "18px"
+  s20: "20px"
+  s22: "22px"
+  s24: "24px"
+  s26: "26px"
+  s28: "28px"
+  s30: "30px"
+  s32: "32px"
+  s34: "34px"
+  s38: "38px"
+  s44: "44px"
+  s48: "48px"
+  s60: "60px"
+  s80: "80px"
+  s88: "88px"
+  shell-max: "1240px"
+  login-max: "1020px"
+  intro-max: "460px"
+  login-card-max: "430px"
+  list-min: "260px"
+  footer-reserve: "155px"
+  mobile-breakpoint: "760px"
+  control-min: "44px"
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-text}"
+    rounded: "{rounded.md}"
+    height: "{spacing.control-min}"
+  panel:
+    backgroundColor: "{colors.surface}"
+    padding: "{spacing.s26}"
+    rounded: "{rounded.panel}"
+  input:
+    rounded: "{rounded.md}"
+---
+
+## Overview
+
+**Scientific Workspace**：从 [CleerScience 官网](https://cleerscience.com/) 提炼的通用深色科技视觉。以近黑蓝底、冷白文字、冰蓝重点、直角薄边框和清晰排版传达秩序；各组件库使用同一份视觉、控件和结构规格。它服务于登录、列表与编辑任务，不把科学品牌、产品名或营销文案带入生成项目。
+
+来源于 2026-10-20 对官网桌面 1440px 和手机 375px 的实际页面及计算样式观察。官网原值包括背景 #02040a、正文 #f4f8ff、冰蓝 #8fc3ff、0px 面板圆角；本模板沿用这些核心值。正文与控件对比度、实体表面、较小标题和 44px 以上操作尺寸是工具型界面的适配决定，并非官网原样复刻。背景视频、品牌标识、全屏叙事和科学插图不属于本模板。
+
+**唯一编辑源**：`design/tokens.json`、`design/widgets.json`、`design/structure.json`、`design/guide.md` 及中立布局/控件样式。执行 `npm run design:sync` 生成本文件、design-tokens.css、design-layout.css、design-widgets.css、design-runtime.json，再执行 `npm run design:check`。不要直接修改派生产物；build/typecheck/lint 会拒绝漂移。YAML 是与组件库无关的有效 token；阴影等非标准字段在正文给出，避免伪装成官方 schema 字段。
+
+## Colors
+
+背景使用 `colors.background`，面板使用 `colors.surface`，输入区使用 `colors.control-background`。正文使用 `colors.text`，辅助说明使用 `colors.muted`，标题不降低透明度。不要把官网用于装饰的低透明度文字直接用于表单标签或必要说明。
+
+`primary` 仅用于主要操作、当前选中项和可见焦点；按钮文字使用 `primary-text`，确保亮色按钮上的深色字可读。`primary-hover` / `primary-active` 表达交互状态。普通表面保持中性冷色，避免整页泛蓝或大面积发光。错误和成功使用各自的 background/border/text 组合，同时保留明确文字或状态角色。
+
+必要文字对比度至少 4.5:1，焦点与操作控件边界至少 3:1；装饰分隔线可以更弱。对比度必须按实际背景检查，不能只比较两个透明 token。新项目若改变主色，需重新验证文字、hover、active 和焦点，不仅替换一个十六进制值。
+
+## Typography
+
+一套无衬线字体贯穿全站：Inter 可用时优先，否则落到系统字体与 PingFang SC / Microsoft YaHei；不主动下载字体。中文正文 16px、行高 1.65，标签 14px，辅助信息 12px；避免将官网 11px 导航字直接当作表单正文。
+
+页面标题 36px、登录标题 48px，手机分别 28px/32px；h2 为 20px，h3 为 18px。标题使用 560–600 字重与轻微负字距，中文不采用官网展示标题的 -0.075em 压缩。`eyebrow` 用 11px、700 字重、0.22em 字距作短标签，不承载唯一操作说明。标题平衡换行，说明文字自然换行，长记录标题允许断行，账号单行省略。
+
+具体字号、字重与行高以 typography 为准。所有套件严格使用同一按钮字号 14px 与行高 20px；不要混用第二套展示字体。
+
+## Layout
+
+沿用工作空间的信息结构：顶栏、页面标题、记录列表与编辑区。桌面 shell-max 为 1240px，水平边距 32px；记录区两栏，登录页说明与表单两栏。面板间距 24px，桌面面板内边距 26px。避免为了科技感给每一行再套卡片。
+
+在 `spacing.mobile-breakpoint`（当前 760px）收为单列，水平边距 18px、面板内边距 20px。375px 不允许横向溢出；操作区允许自然增长，不用全屏固定高度压缩内容。布局 CSS 与媒体查询由同一 token 源生成。
+
+官网的超大留白、全屏分区与宽幅媒体可用于品牌落地页，但不是登录和 CRUD 页面默认规则。新增导航、统计卡或营销分区需要业务需求，不能由设计规范自行扩张功能。
+
+## Elevation & Depth
+
+面板首先依靠深浅表面和 1px 冷色边框分层；阴影为 `0 16px 48px rgba(0,0,0,0.18)`，来自 design/tokens.json 的 effects.panelShadow。控件边框比装饰分隔线更清晰。选中记录增加冰蓝侧线与背景变化，不只靠文字颜色。
+
+官网玻璃面板的 blur(14px) 和影像叠层可作为品牌页面参考；本工具使用实体表面保证阅读和性能，不全局加 backdrop-filter。禁止给每个按钮、输入框加辉光或重阴影。
+
+## Shapes
+
+`rounded.md` 为 0px、`rounded.panel` 为 0px、`rounded.full` 为 0px：按钮、输入、面板和标签保持精确直角。`full` 是沿用的 token 名，在当前主题不代表胶囊。修改形状时同步组件 token；所有尺寸的圆角由套件显式绑定，避免库派生出另一种圆角。
+
+边框厚度通常为 1px。图标沿用所选组件库的简洁线性风格，保持光学尺寸一致；不复制官网 Logo 或专有插图。
+
+## Components
+
+主按钮：冰蓝填充、深色文字；secondary：深色表面与清晰描边；danger：暗红表面与浅红文字。按钮与单行输入高度 44px，保持键盘焦点。default/hover/active/focus/disabled/loading 与输入错误态由 design/widgets.json 定义，套件逐项翻译，不接受原生默认值偏差。颜色派生结果以共享 token 为准；图标使用同一份 SVG 几何，套件不得替换成近似图标。
+
+输入：深色底、冷白输入文字、可读 placeholder，标签始终可见。加载时禁用重复提交；错误后保留输入；空态说明下一步；记录正文以纯文本显示。删除需确认，退出清除当前编辑内容。控件自身焦点、输入和禁用状态由原生控件/套件管理；登录身份、校验、记录状态与请求隔离只在框架无关的 workspace-model 中实现。页面区块顺序和嵌套来自 design/structure.json，框架视图负责绑定。上述行为由业务实现与 Playwright 测试负责，设计文件不替代执行逻辑。
+
+动效只用于短暂状态反馈；遵循 150–250ms 的颜色/边框变化，不新增背景循环、滚动接管或入场延迟。`prefers-reduced-motion: reduce` 下取消非必要动画与过渡。品牌页面如果采用背景媒体，需静态后备、降低亮度、保障文字对比度，并单独验收性能。
+
+## Do's and Don'ts
+
+- UI 开发前读本文件；设计修改先改源，再 sync/check，最后看浏览器真实结果。
+- 复用冷色中性层级、单一字体、直角薄边框与有限强调色；保持所选 UI 库的一致性。
+- 验证默认、hover、active、focus、disabled、loading、empty、error，以及键盘与 375px 布局。
+- 不将来源网站的行业、品牌内容、低对比装饰字或全屏动效当成通用业务要求。
+- 不给每个面板加玻璃、光晕或渐变；库默认值与规格不符时修改套件，不反向修改规范。
+- 全量执行控件/页面比较：位置容差 ≤0.6 CSS px；颜色、圆角、图标几何零容差；必须覆盖 widgets.json 和 structure.json 的全部声明项。
+- 不直接编辑生成文件，不把文档格式通过当成浏览器验收通过，不根据项目简介随机改变视觉。