@cherishxn/agent-scaffold 0.0.0-stage → 1.1.0

package/templates/next-fullstack-antd/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-antd/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-antd/web/src/styles.css

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

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

@@ -0,0 +1,30 @@
+import type * as React from 'react';
+import {Alert as AntAlert,Button as AntButton,ConfigProvider,Input as AntInput,Tag,theme} from 'antd';
+import design from './design-runtime.json';
+import {WidgetIcon} from './widget-icon';
+import type {AlertProps,ButtonProps,FieldProps,InputProps,PanelProps,TextAreaProps} from './widget-types';
+const {tokens,widgets}=design;
+const pixels=(value:string)=>Number.parseFloat(value);
+// Library spellings and DOM corrections live only in this adapter.
+const adapterTheme={algorithm:theme.darkAlgorithm,token:{
+ colorPrimary:tokens.colors.primary,colorPrimaryHover:tokens.colors['primary-hover'],colorPrimaryActive:tokens.colors['primary-active'],
+ colorBgBase:tokens.colors.background,colorBgContainer:tokens.colors['control-background'],colorBgElevated:tokens.colors.surface,
+ colorText:tokens.colors.text,colorTextSecondary:tokens.colors.muted,colorTextPlaceholder:tokens.colors.muted,colorBorder:tokens.colors['control-border'],
+ fontFamily:tokens.typography.body.fontFamily,fontSize:pixels(tokens.typography.body.fontSize),borderRadius:pixels(tokens.rounded.md),borderRadiusLG:pixels(tokens.rounded.md),
+ controlHeight:pixels(widgets.widgets.button.styles.height)
+},components:{Button:{fontWeight:widgets.widgets.button.styles.fontWeight,contentFontSize:pixels(widgets.widgets.button.styles.fontSize),contentFontSizeLG:pixels(widgets.widgets.button.styles.fontSize),primaryColor:tokens.colors['primary-text']},Input:{activeBg:tokens.colors['control-background'],hoverBg:tokens.colors['control-background'],activeShadow:'none'}}};
+const adapterCss=`
+[data-widget="button"].ant-btn::before,[data-widget="button"].ant-btn::after{display:none!important}
+[data-widget="alert"].ant-alert .ant-alert-section{min-width:0;flex:0 1 auto}
+[data-widget="alert"].ant-alert .ant-alert-title{display:block;margin:0;padding:0;font:inherit;color:inherit;line-height:inherit}
+[data-widget="alert"].ant-alert .ant-alert-icon{margin-inline-end:0;color:inherit!important;line-height:inherit!important}
+[data-widget="alert"].ant-alert [data-part="message"]{display:block}
+`;
+export function Button({children,variant='primary',loading=false,disabled,type='button',...props}:ButtonProps){return <AntButton {...props} htmlType={type} type={variant==='primary'?'primary':'default'} danger={variant==='danger'} autoInsertSpace={false} data-widget="button" data-variant={variant} aria-busy={loading||undefined} disabled={disabled||loading}><span data-part="label">{children}</span></AntButton>;}
+export function Input({invalid,...props}:InputProps){return <AntInput {...props} data-widget="input" aria-invalid={invalid||undefined}/>;}
+export function TextArea({invalid,...props}:TextAreaProps){return <AntInput.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 <AntAlert data-widget="alert" data-variant={variant} role={variant==='error'?'alert':'status'} type={variant} showIcon icon={<WidgetIcon kind={variant}/>} title={<span data-part="message">{children}</span>}/>;}
+export function Badge({children}:{children:React.ReactNode}){return <Tag data-widget="badge" className="badge"><span data-part="label">{children}</span></Tag>;}
+export function Theme({children}:{children:React.ReactNode}){return <ConfigProvider wave={{disabled:true}} theme={adapterTheme}><style>{adapterCss}</style>{children}</ConfigProvider>;}

package/templates/next-fullstack-antd/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-antd/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-antd/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-antd/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-antd/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/next-fullstack-shadcn/.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/next-fullstack-shadcn/.agents/skills/project-work/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: project-work
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
+---
+
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/next-fullstack-shadcn/.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/next-fullstack-shadcn/.claude/skills/project-work/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: project-work
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
+---
+
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/next-fullstack-shadcn/.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/next-fullstack-shadcn/.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/next-fullstack-shadcn/.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/next-fullstack-shadcn/.grok/skills/project-work/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: project-work
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
+---
+
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/next-fullstack-shadcn/.scaffold-checks.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "template": "next-fullstack",
+  "ui": "shadcn",
+  "port": 3000,
+  "backend": false
+}

package/templates/next-fullstack-shadcn/AGENTS.md

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

package/templates/next-fullstack-shadcn/CLAUDE.md

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