@xfilecom/xframe 0.1.17 → 0.1.19

package/bin/xframe.js

@@ -38,10 +38,22 @@ Options:
   --front-core <spec>     @xfilecom/front-core (default: ^0.2.1)
   --no-install            스캐폴드만 하고 yarn/npm install 생략
 
+MySQL (shared/config/api/application.yml 의 database.*)
+  --skip-db-prompt        TTY여도 DB 질문 생략 → 아래 기본값 또는 플래그만 반영
+  --db-host <h>           기본 127.0.0.1
+  --db-port <n>           기본 3306
+  --db-user <u>           기본 root
+  --db-password <p>       기본 빈 문자열 (빈 값: --db-password "")
+  --db-name <n>           기본 app
+  --db-pull               install 성공 후 yarn/npm run db:pull 실행 (MySQL 도달 가능할 때)
+
+TTY + --skip-db-prompt 없음 → 위 항목을 순서대로 물어봅니다 (Enter = 기본값).
+  마지막에 db:pull 여부를 [y/N] 로 묻습니다 (--db-pull 이 있으면 질문 생략하고 실행).
+
 Examples:
   npx @xfilecom/xframe@latest my-app
-  npx @xfilecom/xframe my-app --backend-core file:../../../packages/backend-core \\
-    --front-core file:../../../packages/front-core`);
+  npx @xfilecom/xframe my-app --db-host 127.0.0.1 --db-user app --db-password secret --db-name mydb --db-pull
+  npx @xfilecom/xframe my-app --skip-db-prompt --no-install`);
 }
 
 function parseArgs(argv) {
@@ -50,6 +62,20 @@ function parseArgs(argv) {
   let backendCore = '^1.0.0';
   let frontCore = '^0.2.1';
   let skipInstall = false;
+  let skipDbPrompt = false;
+  let dbPull = false;
+  /** @type {{ host?: string, port?: number, user?: string, password?: string, name?: string }} */
+  const dbFromCli = {};
+
+  function takeStringFlag(name, i) {
+    const v = rest[i + 1];
+    if (v === undefined) {
+      console.error(`xframe: ${name} requires a value`);
+      process.exit(1);
+    }
+    i += 1;
+    return { val: v, nextI: i };
+  }
 
   for (let i = 0; i < rest.length; i += 1) {
     const a = rest[i];
@@ -61,24 +87,58 @@ function parseArgs(argv) {
       skipInstall = true;
       continue;
     }
+    if (a === '--skip-db-prompt') {
+      skipDbPrompt = true;
+      continue;
+    }
+    if (a === '--db-pull') {
+      dbPull = true;
+      continue;
+    }
     if (a === '--backend-core') {
-      const v = rest[i + 1];
-      if (!v || v.startsWith('-')) {
-        console.error('xframe: --backend-core requires a value');
-        process.exit(1);
-      }
-      backendCore = v;
-      i += 1;
+      const { val, nextI } = takeStringFlag('--backend-core', i);
+      backendCore = val;
+      i = nextI;
       continue;
     }
     if (a === '--front-core') {
-      const v = rest[i + 1];
-      if (!v || v.startsWith('-')) {
-        console.error('xframe: --front-core requires a value');
+      const { val, nextI } = takeStringFlag('--front-core', i);
+      frontCore = val;
+      i = nextI;
+      continue;
+    }
+    if (a === '--db-host') {
+      const { val, nextI } = takeStringFlag('--db-host', i);
+      dbFromCli.host = val;
+      i = nextI;
+      continue;
+    }
+    if (a === '--db-port') {
+      const { val, nextI } = takeStringFlag('--db-port', i);
+      dbFromCli.port = parseInt(val, 10);
+      if (!Number.isFinite(dbFromCli.port)) {
+        console.error('xframe: --db-port must be a number');
         process.exit(1);
       }
-      frontCore = v;
-      i += 1;
+      i = nextI;
+      continue;
+    }
+    if (a === '--db-user') {
+      const { val, nextI } = takeStringFlag('--db-user', i);
+      dbFromCli.user = val;
+      i = nextI;
+      continue;
+    }
+    if (a === '--db-password') {
+      const { val, nextI } = takeStringFlag('--db-password', i);
+      dbFromCli.password = val;
+      i = nextI;
+      continue;
+    }
+    if (a === '--db-name') {
+      const { val, nextI } = takeStringFlag('--db-name', i);
+      dbFromCli.name = val;
+      i = nextI;
       continue;
     }
     if (a.startsWith('-')) {
@@ -93,7 +153,126 @@ function parseArgs(argv) {
     projectDir = a;
   }
 
-  return { projectDir, backendCore, frontCore, skipInstall };
+  return {
+    projectDir,
+    backendCore,
+    frontCore,
+    skipInstall,
+    skipDbPrompt,
+    dbPull,
+    dbFromCli,
+  };
+}
+
+/** YAML 단일 인용 내용 이스케이프 */
+function yamlSingleQuotedEscape(s) {
+  return String(s).replace(/'/g, "''");
+}
+
+/** 식별자형이면 따옴표 없이, 아니면 작은따옴표 */
+function yamlScalar(v) {
+  const s = String(v);
+  if (/^[A-Za-z0-9_.@-]+$/.test(s)) return s;
+  return `'${yamlSingleQuotedEscape(s)}'`;
+}
+
+/**
+ * 최상위 `database:` 블록만 수정 (같은 들여쓰기의 `server.port` 등과 구분).
+ *
+ * @param {string} targetRoot
+ * @param {{ host: string, port: number, user: string, password: string, name: string }} db
+ */
+function patchApplicationYmlDatabase(targetRoot, db) {
+  const p = path.join(targetRoot, 'shared', 'config', 'api', 'application.yml');
+  if (!fs.existsSync(p)) {
+    console.warn('xframe: application.yml not found, skip DB patch');
+    return;
+  }
+  const portN = Number.isFinite(Number(db.port)) ? Number(db.port) : 3306;
+  const pwd = `'${yamlSingleQuotedEscape(db.password)}'`;
+  const lines = fs.readFileSync(p, 'utf8').split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i] === 'database:') {
+      i += 1;
+      while (i < lines.length) {
+        const line = lines[i];
+        // 루트 database 직계만 (들여쓰기 2칸 + 키). 4칸 이상은 core.database 등 하위 블록.
+        if (line === '' || /^  [A-Za-z_#]/.test(line)) {
+          if (/^  host:/.test(line)) lines[i] = `  host: ${yamlScalar(db.host)}`;
+          else if (/^  port:/.test(line)) lines[i] = `  port: ${portN}`;
+          else if (/^  user:/.test(line)) lines[i] = `  user: ${yamlScalar(db.user)}`;
+          else if (/^  password:/.test(line)) lines[i] = `  password: ${pwd}`;
+          else if (/^  name:/.test(line)) lines[i] = `  name: ${yamlScalar(db.name)}`;
+          i += 1;
+          continue;
+        }
+        break;
+      }
+      break;
+    }
+    i += 1;
+  }
+  fs.writeFileSync(p, lines.join('\n'), 'utf8');
+}
+
+const DB_DEFAULTS = {
+  host: '127.0.0.1',
+  port: 3306,
+  user: 'root',
+  password: '',
+  name: 'app',
+};
+
+/**
+ * @param {{ host?: string, port?: number, user?: string, password?: string, name?: string }} fromCli
+ * @param {boolean} skipDbPrompt
+ * @param {boolean} wantDbPullFlag
+ * @returns {Promise<{ db: typeof DB_DEFAULTS, runDbPull: boolean }>}
+ */
+async function collectDatabaseConfig(fromCli, skipDbPrompt, wantDbPullFlag) {
+  let db = { ...DB_DEFAULTS, ...fromCli };
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && !skipDbPrompt;
+  const readline = require('node:readline/promises');
+  const rl = interactive ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
+
+  try {
+    if (interactive && rl) {
+      console.log('\nxframe: MySQL 연결 정보 (Enter = 괄호 안 기본값)\n');
+      const ask = async (label, key, def) => {
+        if (fromCli[key] !== undefined) return;
+        const hint = def === '' ? '(비워두기)' : def;
+        const line = (await rl.question(`${label} [${hint}]: `)).trim();
+        if (line !== '') {
+          if (key === 'port') {
+            const n = parseInt(line, 10);
+            if (Number.isFinite(n)) db[key] = n;
+          } else {
+            db[key] = line;
+          }
+        }
+      };
+      await ask('Host', 'host', DB_DEFAULTS.host);
+      await ask('Port', 'port', String(DB_DEFAULTS.port));
+      await ask('User', 'user', DB_DEFAULTS.user);
+      await ask('Password', 'password', DB_DEFAULTS.password);
+      await ask('Database name', 'name', DB_DEFAULTS.name);
+    } else {
+      db = { ...DB_DEFAULTS, ...fromCli };
+    }
+
+    let runDbPull = wantDbPullFlag;
+    if (interactive && rl && !wantDbPullFlag) {
+      const a = (await rl.question('\n지금 yarn/npm db:pull (스키마 역추출) 을 실행할까요? [y/N] '))
+        .trim()
+        .toLowerCase();
+      runDbPull = a === 'y' || a === 'yes';
+    }
+
+    return { db, runDbPull };
+  } finally {
+    if (rl) await rl.close();
+  }
 }
 
 /** yarn 우선, 없거나 실패 시 npm (부모 셸 PATH 그대로 — shell:true 쓰면 sh라 yarn/nvm PATH가 빠지는 경우가 많음) */
@@ -137,6 +316,27 @@ function installDependencies(cwd) {
   return false;
 }
 
+function executeDbPull(cwd) {
+  console.log('\nxframe: db:pull 실행 (drizzle-kit introspect)…');
+  const opts = { cwd, stdio: 'inherit', env: process.env };
+  const y = spawnSync('yarn', ['run', 'db:pull'], opts);
+  if (y.status === 0) {
+    console.log('xframe: db:pull 완료.');
+    return true;
+  }
+  if (y.error && y.error.code === 'ENOENT') {
+    console.log('xframe: yarn 없음 → npm run db:pull 시도');
+  }
+  const n = spawnSync('npm', ['run', 'db:pull'], opts);
+  if (n.status === 0) {
+    console.log('xframe: db:pull 완료.');
+    return true;
+  }
+  console.error('xframe: db:pull 실패. 프로젝트 루트에서 수동으로 yarn db:pull / npm run db:pull 하세요.');
+  console.error('xframe: (비밀번호가 비어 있으면 drizzle-kit 이 거절할 수 있습니다. application.yml database.password 를 확인하세요.)');
+  return false;
+}
+
 /** 모노레포 템플릿 tsconfig 의 @xfilecom/front-core 경로 → 생성 앱의 node_modules 기준 */
 const TEMPLATE_FRONT_CORE_TS_PATH = '../../../../front-core/src/index.ts';
 const SCAFFOLD_FRONT_CORE_TS_PATH = '../../node_modules/@xfilecom/front-core';
@@ -207,8 +407,16 @@ function readCliVersion() {
   }
 }
 
-function main() {
-  const { projectDir, backendCore, frontCore, skipInstall } = parseArgs(process.argv);
+async function main() {
+  const {
+    projectDir,
+    backendCore,
+    frontCore,
+    skipInstall,
+    skipDbPrompt,
+    dbPull: dbPullFlag,
+    dbFromCli,
+  } = parseArgs(process.argv);
 
   if (!projectDir) {
     console.error('xframe: missing <project-directory>\n');
@@ -248,6 +456,10 @@ function main() {
 
   fs.cpSync(templateRoot, targetRoot, { recursive: true });
 
+  const { db, runDbPull: shouldDbPull } = await collectDatabaseConfig(dbFromCli, skipDbPrompt, dbPullFlag);
+  patchApplicationYmlDatabase(targetRoot, db);
+  console.log(`xframe: wrote database.* → ${path.join('shared', 'config', 'api', 'application.yml')}`);
+
   const vars = {
     PACKAGE_NAME: packageName,
     SERVICE_LABEL: `${packageName}-api`,
@@ -276,13 +488,22 @@ Included:
   • shared/       — config/api·web, schema, sql, endpoint
   • .cursor/rules — @xfilecom/backend-core / front-core 사용 가이드 (.mdc)`);
 
+  let installOk = true;
   if (!skipInstall) {
-    const ok = installDependencies(targetRoot);
-    if (!ok) {
+    installOk = installDependencies(targetRoot);
+    if (!installOk) {
       process.exit(1);
     }
   }
 
+  if (shouldDbPull) {
+    if (skipInstall) {
+      console.warn('xframe: --no-install 이라 db:pull 을 건너뜁니다 (먼저 install 후 수동 실행).');
+    } else {
+      executeDbPull(targetRoot);
+    }
+  }
+
   const rel = path.relative(process.cwd(), targetRoot) || '.';
   console.log(`
 Next:
@@ -292,4 +513,7 @@ Next:
   (설치 생략: npx @xfilecom/xframe <dir> --no-install)`);
 }
 
-main();
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/xframe",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Scaffold full-stack app: Nest + @xfilecom/backend-core, Vite/React + @xfilecom/front-core",
   "license": "UNLICENSED",
   "bin": {

package/template/shared/config/api/application.yml

@@ -17,9 +17,9 @@ http:
 database:
   host: 127.0.0.1
   port: 3306
-  user: xfilecom
-  password: milk1209
-  name: usdt-market-place
+  user: root
+  password: ''
+  name: app
   ssl: false
   connectionLimit: 10
 

package/template/web/admin/src/main.tsx

@@ -1,7 +1,9 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import '@xfilecom/front-core/tokens.css';
+import '../../shared/src/styles/xfc-theme.css';
 import '@xfilecom/front-core/base.css';
+import '../../shared/src/styles/app.css';
 import { App } from './App';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

package/template/web/client/src/App.tsx

@@ -1,18 +1,24 @@
-import { Badge, Text } from '@xfilecom/front-core';
+import { useState } from 'react';
+import { Badge, Button, Stack, Text } from '@xfilecom/front-core';
 import {
   Shell,
   useHealthStatus,
   FALLBACK_API_BASE_URL,
 } from '__WEB_SHARED_WORKSPACE__';
+import { FrontCoreShowcase } from './FrontCoreShowcase';
 
 const apiBase = import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL;
 const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__';
 
+type Tab = 'api' | 'atoms';
+
 export function App() {
+  const [tab, setTab] = useState<Tab>('atoms');
   const { text, error } = useHealthStatus(apiBase);
 
   return (
     <Shell
+      wide={tab === 'atoms'}
       title={title}
       subtitle={
         <>
@@ -23,15 +29,36 @@ export function App() {
         </>
       }
     >
-      {error ? (
-        <Text as="pre" variant="body" style={{ color: 'var(--xfc-warning)', margin: 0, whiteSpace: 'pre-wrap' }}>
-          {error}
-        </Text>
-      ) : (
-        <Text as="pre" variant="small" style={{ margin: 0, overflow: 'auto' }}>
-          {text}
-        </Text>
-      )}
+      <Stack direction="column" gap="md" align="stretch">
+        <Stack direction="row" gap="sm" align="center" style={{ flexWrap: 'wrap' }}>
+          <Button
+            type="button"
+            variant={tab === 'atoms' ? 'primary' : 'secondary'}
+            onClick={() => setTab('atoms')}
+          >
+            Atoms 예시
+          </Button>
+          <Button
+            type="button"
+            variant={tab === 'api' ? 'primary' : 'secondary'}
+            onClick={() => setTab('api')}
+          >
+            API health
+          </Button>
+        </Stack>
+
+        {tab === 'atoms' ? (
+          <FrontCoreShowcase />
+        ) : error ? (
+          <Text as="pre" variant="body" style={{ color: 'var(--xfc-warning)', margin: 0, whiteSpace: 'pre-wrap' }}>
+            {error}
+          </Text>
+        ) : (
+          <Text as="pre" variant="small" style={{ margin: 0, overflow: 'auto' }}>
+            {text}
+          </Text>
+        )}
+      </Stack>
     </Shell>
   );
 }

package/template/web/client/src/FrontCoreShowcase.tsx

@@ -0,0 +1,177 @@
+import { useCallback, useId, useRef, useState, type ReactNode } from 'react';
+import {
+  Badge,
+  Box,
+  Button,
+  Card,
+  Input,
+  InlineErrorList,
+  LoadingOverlay,
+  Stack,
+  Text,
+  Toast,
+  ToastList,
+  ToastSeverityIcon,
+  type InlineErrorEntry,
+  type ToastEntry,
+  type ToastSeverity,
+} from '@xfilecom/front-core';
+
+function SectionTitle({ children }: { children: ReactNode }) {
+  return (
+    <Text as="h2" variant="section" style={{ margin: 0 }}>
+      {children}
+    </Text>
+  );
+}
+
+export function FrontCoreShowcase() {
+  const uid = useId();
+  const toastSeq = useRef(0);
+  const errorSeq = useRef(0);
+  const [toasts, setToasts] = useState<ToastEntry[]>([]);
+  const [errors, setErrors] = useState<InlineErrorEntry[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  const pushToast = useCallback(
+    (severity: ToastSeverity) => {
+      toastSeq.current += 1;
+      const id = `${uid}-t-${toastSeq.current}`;
+      setToasts((prev) => [...prev, { id, severity, message: `${severity} 메시지 예시` }]);
+    },
+    [uid],
+  );
+
+  const addError = useCallback(() => {
+    errorSeq.current += 1;
+    const id = `${uid}-e-${errorSeq.current}`;
+    setErrors((prev) => [...prev, { id, message: `샘플 에러 #${errorSeq.current}` }]);
+  }, [uid]);
+
+  return (
+    <>
+      <InlineErrorList errors={errors} onDismiss={(id) => setErrors((e) => e.filter((x) => x.id !== id))} />
+      <ToastList toasts={toasts} onDismiss={(id) => setToasts((t) => t.filter((x) => x.id !== id))} />
+      <LoadingOverlay active={loading} message="로딩 중…" />
+
+      <Stack direction="column" gap="lg" align="stretch">
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Text</SectionTitle>
+            <Text variant="title">title</Text>
+            <Text variant="section">section</Text>
+            <Text variant="body">body — 본문 텍스트</Text>
+            <Text variant="muted">muted</Text>
+            <Text variant="small">small</Text>
+            <Text variant="accent">accent</Text>
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Badge</SectionTitle>
+            <Stack direction="row" gap="sm" align="center">
+              <Badge tone="neutral">neutral</Badge>
+              <Badge tone="accent">accent</Badge>
+              <Badge tone="success">success</Badge>
+              <Badge tone="danger">danger</Badge>
+            </Stack>
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Button</SectionTitle>
+            <Stack direction="row" gap="sm" align="center" style={{ flexWrap: 'wrap' }}>
+              <Button variant="primary">primary</Button>
+              <Button variant="secondary">secondary</Button>
+              <Button variant="outline">outline</Button>
+              <Button variant="muted">muted</Button>
+              <Button variant="ghost">ghost</Button>
+              <Button variant="primary" disabled>
+                disabled
+              </Button>
+            </Stack>
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Input</SectionTitle>
+            <label htmlFor={`${uid}-email`}>
+              <Text as="span" variant="labelBlock">
+                이메일
+              </Text>
+            </label>
+            <Input id={`${uid}-email`} type="email" placeholder="you@example.com" autoComplete="email" />
+            <Input placeholder="비활성" disabled />
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Box · Stack · Card</SectionTitle>
+            <Stack direction="row" gap="md" align="stretch" style={{ flexWrap: 'wrap' }}>
+              <Box padding="md" style={{ border: '1px dashed var(--xfc-border-strong)', borderRadius: 'var(--xfc-radius-xs)' }}>
+                <Text variant="small">Box padding md</Text>
+              </Box>
+              <Card style={{ flex: '1 1 140px', minWidth: 0 }}>
+                <Text variant="small">중첩 Card</Text>
+              </Card>
+            </Stack>
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>ToastSeverityIcon</SectionTitle>
+            <Stack direction="row" gap="lg" align="center" style={{ color: 'var(--xfc-fg)' }}>
+              <ToastSeverityIcon severity="info" />
+              <ToastSeverityIcon severity="success" />
+              <ToastSeverityIcon severity="warn" />
+              <ToastSeverityIcon severity="error" />
+            </Stack>
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>Toast (단일)</SectionTitle>
+            <Toast severity="info" message="인라인 Toast 한 줄" onDismiss={() => {}} />
+          </Stack>
+        </Card>
+
+        <Card>
+          <Stack direction="column" gap="md" align="stretch">
+            <SectionTitle>ToastList · InlineErrorList · LoadingOverlay</SectionTitle>
+            <Text variant="small" style={{ color: 'var(--xfc-fg-muted)' }}>
+              ToastList / InlineErrorList / LoadingOverlay 는 화면 고정 레이어입니다. 아래 버튼으로 띄워 보세요.
+            </Text>
+            <Stack direction="row" gap="sm" align="center" style={{ flexWrap: 'wrap' }}>
+              <Button type="button" variant="secondary" onClick={() => pushToast('info')}>
+                toast info
+              </Button>
+              <Button type="button" variant="secondary" onClick={() => pushToast('success')}>
+                toast success
+              </Button>
+              <Button type="button" variant="secondary" onClick={() => pushToast('warn')}>
+                toast warn
+              </Button>
+              <Button type="button" variant="secondary" onClick={() => pushToast('error')}>
+                toast error
+              </Button>
+            </Stack>
+            <Stack direction="row" gap="sm" align="center" style={{ flexWrap: 'wrap' }}>
+              <Button type="button" variant="outline" onClick={addError}>
+                에러 배너 추가
+              </Button>
+              <Button type="button" variant="outline" onClick={() => setLoading((v) => !v)}>
+                로딩 오버레이 {loading ? '끄기' : '켜기'}
+              </Button>
+            </Stack>
+          </Stack>
+        </Card>
+      </Stack>
+    </>
+  );
+}

package/template/web/client/src/main.tsx

@@ -1,7 +1,9 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import '@xfilecom/front-core/tokens.css';
+import '../../shared/src/styles/xfc-theme.css';
 import '@xfilecom/front-core/base.css';
+import '../../shared/src/styles/app.css';
 import { App } from './App';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(

package/template/web/shared/package.json

@@ -10,7 +10,9 @@
       "types": "./src/index.ts",
       "import": "./src/index.ts",
       "default": "./src/index.ts"
-    }
+    },
+    "./styles/xfc-theme.css": "./src/styles/xfc-theme.css",
+    "./styles/app.css": "./src/styles/app.css"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json"

package/template/web/shared/src/components/Shell.tsx

@@ -1,16 +1,17 @@
 import type { ReactNode } from 'react';
 import { Card, Stack, Text } from '@xfilecom/front-core';
-import '../styles/app.css';
 
 export type ShellProps = {
   title: string;
   subtitle?: ReactNode;
   children?: ReactNode;
+  /** true면 폭 제한(480) 없음 — atoms 갤러리 등 */
+  wide?: boolean;
 };
 
-export function Shell({ title, subtitle, children }: ShellProps) {
+export function Shell({ title, subtitle, children, wide = false }: ShellProps) {
   return (
-    <div className="xfc-page xfc-page--narrow">
+    <div className={wide ? 'xfc-page' : 'xfc-page xfc-page--narrow'}>
       <header className="xfc-hero">
         <Text as="h1" variant="appbar">
           {title}

package/template/web/shared/src/styles/app.css

@@ -1,6 +1,11 @@
 /**
  * 앱 레이아웃 — `html/html` 모바일 프레임(폭 480)에 맞춤.
- * 토큰·atoms는 @xfilecom/front-core.
+ *
+ * 엔트리에서 @xfilecom/front-core/base.css 다음에 로드하세요.
+ * 이 파일은 tokens / xfc-theme / atoms 이후이므로
+ *   - 레이아웃(.xfc-page 등)과
+ *   - 필요 시 atoms(.xfc-btn, .xfc-toast 등) 덮어쓰기
+ * 를 같은 파일에 둘 수 있습니다.
  */
 
 .xfc-page {
@@ -61,3 +66,10 @@
   background: var(--xfc-bg);
   border-bottom: 1px solid var(--xfc-border-header);
 }
+
+/* —— optional: front-core atoms 오버라이드 (base.css 이후 로드됨) —— */
+/*
+.xfc-btn--primary {
+  border-radius: var(--xfc-radius-md);
+}
+*/

package/template/web/shared/src/styles/xfc-theme.css

@@ -0,0 +1,18 @@
+/**
+ * 앱·브랜드별 디자인 토큰 덮어쓰기.
+ *
+ * 엔트리(main.tsx)에서 반드시 다음 순서로 넣으세요:
+ *   1. @xfilecom/front-core/tokens.css
+ *   2. 이 파일 (xfc-theme.css)
+ *   3. @xfilecom/front-core/base.css   ← atoms 가 var(--xfc-*) 를 참조
+ *   4. app.css                         ← 레이아웃 + atoms(.xfc-*) 클래스 오버라이드
+ *
+ * 여기서 :root 의 --xfc-* 를 바꾸면 Button·Input·Toast 등 front-core atoms 스타일에 그대로 반영됩니다.
+ */
+
+/* 예시 (필요할 때 주석 해제)
+:root {
+  --xfc-accent: #2a5bff;
+  --xfc-accent-hover: #2248e6;
+}
+*/