DESIGN.md Studio

DESIGN.md คือข้อตกลงเรื่องหน้าตาและความรู้สึกของ product ไม่ใช่ specification ของสิ่งที่ product ต้องทำ

ก่อนมาที่นี่ คุณต้องมี PRODUCT_PLAN.md ที่รับแล้ว: Product Map บอกว่ามีหน้าและเส้นทางใดบ้าง ส่วน User Stories และ Acceptance Criteria บอก behavior, state และผลที่ผู้ใช้ต้องเห็น DESIGN.md ไม่คัดลอกหรือเปลี่ยนสิ่งเหล่านั้น มันเพิ่มคำตอบว่า เมื่อ AI สร้างสิ่งที่ตกลงแล้ว หน้าตาควรสม่ำเสมอ อ่านง่าย และเหมาะกับบริบทใช้งานอย่างไร

เราใช้รูปแบบ Google Labs DESIGN.md alpha: YAML ด้านบนเก็บ token ที่ AI อ่านได้ตรงกัน และหัวข้อ Markdown ด้านล่างอธิบายเหตุผลให้คนตรวจได้ ไฟล์ต้องชื่อ DESIGN.md (ตัวพิมพ์ใหญ่ทั้งหมด) และอยู่ที่ root ของ repository ข้าง README.md, PRODUCT_PLAN.md และ BUILD_PLAN.md

เมื่อจบหน้านี้ คุณจะมี Stitch board/screenshots ที่ผ่าน scope review และ DESIGN.md ที่พร้อมส่งต่อให้ AI ก่อนเริ่ม guided first build ใน Module 2 แต่ยังไม่มี UI code

ขั้นที่ 1 · ใช้ Stitch ทำให้ Primary Path มองเห็นครบ loop

ก่อนเลือกสีหรือ component ให้ใช้ Stitch สร้างภาพของ Primary Success Path ทั้งเส้น จาก PRODUCT_PLAN.md ที่ผ่านแล้ว: ผู้ใช้เห็นหนังสือ → ค้นชื่อหรือ ISBN → เห็นว่า “มีแล้ว” หรือ “ยังไม่มี” → เพิ่มเมื่อจำเป็น → กลับมารู้สถานะชัดเจนพอจะตัดสินใจซื้อ

นี่คือ visual hypothesis เพื่อให้คนตรวจความต่อเนื่องของคุณค่า ไม่ใช่คำสั่งให้สร้างทุก screen ใน Module 2 ProudVault จะสร้าง Search/ISBN จริงใน Module 3; Module 2 สร้างเพียง identity, Vault, Asset และ usable states

ส่งเข้า Stitch เฉพาะข้อมูลที่อนุมัติแล้ว:

• Primary Path, Site Map, Story/Acceptance Criteria ที่เกี่ยวข้อง และ Non-goals จาก PRODUCT_PLAN.md
• บริบทผู้ใช้และอุปกรณ์ เช่น ใช้โทรศัพท์มือเดียวในร้านหนังสือและต้องอ่านคำตอบเร็ว
• design rules ที่ร่างไว้ ถ้ามี

หยุด generate เมื่อภาพพอให้ตรวจ action, information hierarchy, empty/invalid/result states และจุดจบของ loop ได้ ไม่ต้อง polish pixel หรือเติม feature ให้เหมือน product สำเร็จรูป

ขั้นที่ 2 · Review ภาพกับ Product Plan ก่อนส่งต่อ

เปิดทีละ screen แล้วทำตารางนี้ร่วมกับ AI หรือผู้สอน:

ใช้ได้เพียงสามคำตัดสิน:

• KEEP — มี trace กลับไปแผนและจะเก็บเป็น visual rule หรือสร้างตาม build scope
• DEFER — อยู่ในแผน แต่เป็น Module หลังหรือ phase ที่ยังไม่ถึง
• REMOVE — ไม่มีในแผน, ขัด Non-goals หรือเป็น claim ที่ยังไม่มี evidence

อย่ารับ navigation, settings, analytics, recommendation, security claim, external metadata หรือ interaction ใหม่เพียงเพราะ Stitch ทำให้ดูน่าใช้

เมื่อ review แล้ว เก็บลิงก์/ภาพและตารางนี้เป็นหลักฐานของ visual review ไม่ต้อง export code จาก Stitch

ขั้นที่ 3 · รู้ก่อนว่า DESIGN.md เก็บอะไร

ไฟล์นี้ไม่ใช่ภาพ mockup และไม่ใช่รายการหน้า แต่เป็นกติกาที่ AI นำไปใช้ซ้ำเมื่อสร้าง UI:

YAML ด้านบนเก็บค่าที่ AI นำไปใช้ได้ ส่วน Markdown ด้านล่างอธิบายเหตุผลและบริบทของกติกา

ขั้นที่ 4 · สกัด rules จาก Stitch ก่อนใช้ reference เสริม

เริ่มจากสิ่งที่ผ่าน review แล้วใน Stitch: สีที่ใช้กับ action, hierarchy ของข้อความ, spacing, รูปทรงของ control, card และ treatment ของ empty/invalid/focus state เขียนเป็น Stitch-ready extract สั้น ๆ เพื่อทดลอง generate ซ้ำได้ เช่น “พื้นสว่าง, ตัวอักษรเข้ม, primary action สีน้ำเงินเพียงหนึ่ง action, control สูงอย่างน้อย 44px และ mobile single column”

หาก visual language ยังไม่ชัด จึงค่อยเลือก design system หนึ่งแบบจาก shadcn.io Design Gallery เป็น reference เสริม ไม่ต้องใช้ reference หาก rules ที่ผ่าน review ชัดพอแล้ว

ขั้นที่ 5 · เลือก reference ที่เหมาะกับ product (เมื่อจำเป็น)

เปิด shadcn.io Design Gallery แล้วเลือก design system หนึ่งแบบ ที่ใกล้กับความรู้สึกของ product ไม่ต้องเลือกเพราะเป็น brand ที่ชอบอย่างเดียว ให้เทียบกับ ผู้ใช้และบริบทใน PRODUCT_PLAN.md ก่อน:

• อ่านง่ายไหม — สี ตัวอักษร และลำดับชั้นเหมาะกับสถานที่และอุปกรณ์ที่ใช้หรือไม่
• บุคลิกตรงไหม — ดูสงบ จริงจัง เป็นมิตร หรือกระฉับกระเฉงตรงกับ product หรือไม่
• นำไปใช้ต่อได้ไหม — spacing รูปทรง และ component ใกล้กับหน้าที่ต้องสร้างหรือไม่

เลือกแล้วให้จดชื่อ reference, link และเหตุผลสามข้อที่โยงกลับมาหา product เช่น “พื้นสว่างช่วยให้อ่านชื่อหนังสือเร็ว”, “มี primary action เดียวจึงไม่แย่งสายตา” และ “spacing โปร่งเหมาะกับการใช้โทรศัพท์มือเดียว”

ใช้ reference เป็นจุดเริ่มต้นเท่านั้น ห้าม copy brand, logo, ภาพหรือข้อความของเจ้าของต้นฉบับ

ก่อนเขียน ให้เปิด PRODUCT_PLAN.md เพื่อทวน:

• Primary user และบริบทการใช้ ที่มีผลต่อการอ่านและการกด
• story/criterion ID ที่ UI ในรอบนี้ต้องรองรับ
• Product Map ที่รับแล้ว — ใช้อ้างอิงเท่านั้น ห้ามวาด map ใหม่ที่นี่
• Non-goals — ห้ามเพิ่ม decoration หรือ component เพื่อ feature ที่ยังไม่ทำ

ขั้นที่ 6 · ดาวน์โหลดไฟล์ต้นฉบับมาเป็น reference

เปิดหน้าของ design system ที่เลือก แล้วกด Download DESIGN.md จากนั้น:

1. เปลี่ยนชื่อไฟล์เป็น REFERENCE_DESIGN.md
2. วางไว้ใน repository root ชั่วคราว ข้าง PRODUCT_PLAN.md
3. เปิดอ่านให้เห็น Colors, Typography, Layout, Shapes, Components และ Do’s and Don’ts
4. อย่าเพิ่งเปลี่ยนชื่อเป็น DESIGN.md และอย่าให้ AI นำไปสร้าง UI

ไฟล์ที่ดาวน์โหลดมาคือวัตถุดิบจาก design system ของคนอื่น ไม่ใช่ visual contract ของ project เรา ขั้นถัดไปต้องคัดหลักการที่เหมาะ ปรับ token และตัดสิ่งที่ไม่เกี่ยวออกก่อน

ขั้นที่ 7 · ให้ AI ร่าง DESIGN.md จาก rules ที่ผ่าน review

ส่ง PRODUCT_PLAN.md, Stitch-ready extract และ (ถ้ามี) REFERENCE_DESIGN.md ไปพร้อม prompt นี้ AI ต้องเสนอทิศทางก่อน ยังไม่เขียนไฟล์ทันที หากไม่มี reference ให้ตัดบรรทัด REFERENCE_DESIGN.md ออก

อ่าน PRODUCT_PLAN.md, Stitch-ready design rules ที่ผ่าน scope review และ REFERENCE_DESIGN.md (ถ้ามี)

ช่วยเสนอการปรับ reference นี้เป็น DESIGN.md สำหรับ project ของฉัน
ใช้บริบทจริงใน PRODUCT_PLAN.md และ rules ที่ผ่าน review เป็นหลัก; reference เป็นเพียง input เสริม
ห้าม copy ชื่อ brand, logo, ภาพ ข้อความ หรือ token ที่ไม่เหมาะกับ project

ก่อนเขียนไฟล์ ให้อธิบายว่า:
1. จะเก็บหลักการใดจาก reference
2. จะปรับสี ตัวอักษร spacing รูปทรง และ component อย่างไรให้เป็นของ project นี้
3. จะตัดอะไรออกเพราะไม่เกี่ยวกับ product นี้

ตรวจให้กติกาครอบ Colors, Typography, Spacing & shapes, Components และ Do's and Don'ts
ห้ามเพิ่ม page, flow, state, feature หรือ behavior ที่ไม่มีใน PRODUCT_PLAN.md

รอให้ฉัน Approve, Reject หรือ Request changes ก่อนเขียน DESIGN.md
หลังอนุมัติ ให้ใช้ Google Labs DESIGN.md format เวอร์ชัน alpha ตาม template ใน Studio นี้
ห้ามสร้าง UI หรือแก้ code ในขั้นนี้

ขั้นที่ 8 · ตรวจความครบถ้วนก่อนใช้จริง

AI ร่างได้ แต่เจ้าของ product รับรอง design contract ก่อนใช้สร้าง UI ตรวจทีละข้อ แล้วบอก AI ให้แก้เฉพาะข้อที่ไม่ผ่าน

• ไฟล์ชื่อ DESIGN.md และอยู่ที่ repository root
• YAML เริ่มและจบด้วย --- และมี version: alpha, name, colors, typography, rounded, spacing, components
• token มีค่าจริงที่นำไปใช้ได้ ไม่ใช่คำกว้าง ๆ เช่น “สีฟ้าสวย ๆ”
• หัวข้อ Markdown มีครบและเรียงตาม: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do’s and Don’ts
• Overview เชื่อม visual direction กับผู้ใช้และบริบทจริง ไม่ใช่แค่คำว่า “modern” หรือ “minimal”
• มีสี primary และคู่ text/background ที่อ่านได้อย่างน้อย WCAG AA 4.5:1 สำหรับข้อความปกติ
• font, body size, spacing, touch target และ focus treatment เหมาะกับอุปกรณ์ของผู้ใช้
• component ทุกตัวเป็นกติกาหน้าตา และมี Traceability กลับไปยัง story/criterion ID ที่มีอยู่จริง
• ไม่มี Product Map, screen map, navigation flow, state transition หรือ behavior specification ซ้ำอยู่ในไฟล์นี้
• ไม่มี feature หรือ component ของ Non-goals หลุดเข้ามา
• reference ถูกแปลงเป็นหลักการของ product ตัวเอง ไม่ได้ copy brand ของคนอื่น
• Stitch screens ทุกจุดถูกตัดสิน KEEP, DEFER หรือ REMOVE พร้อม trace กลับไป Product Plan
• ยังไม่มี UI code หรือ implementation ใหม่

เมื่อผ่าน gate:

1. เก็บ DESIGN.md ที่ repository root
2. ลบ REFERENCE_DESIGN.md ออกจาก project เพื่อไม่ให้ AI สับสนว่าไฟล์ใดเป็น source of truth
3. ให้ BUILD_PLAN.md ระบุว่า DESIGN.md เป็น source of truth เรื่อง visual rules
4. ให้ PRODUCT_PLAN.md เป็น source of truth เรื่อง product behavior ต่อไป

Stitch MCP จะถูกต่อใน Build Gate หลัง BUILD_PLAN.md ผ่านแล้ว ไม่ต้องใส่ API key ลง repository และไม่ต้องหยุดหากต่อไม่สำเร็จ: ใช้ DESIGN.md กับ screenshots ที่ผ่าน review เป็น design context แทน

ขั้นที่ 9 · เทียบกับตัวอย่างที่ทำเสร็จแล้ว

---
version: alpha
name: ProudVault
description: A calm, readable mobile web identity for a personal book shelf.
colors:
  primary: "#1D4ED8"
  primary-hover: "#1E40AF"
  on-primary: "#FFFFFF"
  background: "#F8FAFC"
  surface: "#FFFFFF"
  text: "#0F172A"
  text-muted: "#475569"
  border: "#CBD5E1"
  focus: "#F59E0B"
typography:
  display:
    fontFamily: "system-ui, sans-serif"
    fontSize: 1.5rem
    fontWeight: 700
    lineHeight: 1.25
  body:
    fontFamily: "system-ui, sans-serif"
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
  label:
    fontFamily: "system-ui, sans-serif"
    fontSize: 0.875rem
    fontWeight: 600
    lineHeight: 1.4
rounded:
  sm: 6px
  md: 12px
  pill: 999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label}"
    rounded: "{rounded.md}"
    padding: 12px
    height: 44px
  input-default:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    typography: "{typography.body}"
    rounded: "{rounded.sm}"
    padding: 12px
    height: 44px
  card-book:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    rounded: "{rounded.md}"
    padding: 16px
---

## Overview

ProudVault feels like a reliable pocket catalogue: calm enough to scan in a bookstore, clear enough to make a quick decision. Use one confident blue action color, generous whitespace, and readable text rather than a decorative bookshelf theme. This visual direction serves a phone user who may be standing, holding a book, and glancing at a bright screen.

Reference inspiration: editorial clarity, restrained cards, and one obvious primary action. It does not copy another product's brand, logo, imagery, or layout.

## Colors

- **Primary `#1D4ED8`** is reserved for the most important available action.
- **Background `#F8FAFC`**, **surface `#FFFFFF`**, and **text `#0F172A`** keep reading calm and high contrast.
- **Muted text `#475569`** is for supporting information, never the only carrier of an important result.
- **Focus `#F59E0B`** creates a clearly visible keyboard focus ring against both surface and primary blue.
- Normal text on its stated surface must meet WCAG AA 4.5:1 or better; verify any new pairing before accepting it.

## Typography

Use the system sans-serif stack so Thai text, book titles, and ISBN digits remain readable without a font download. Body text is at least `1rem` (16px). Use `display` only for the product name and major page title; use `label` for controls and small headings. Do not compress long book titles with tiny type.

## Layout

Design from a single-column mobile baseline. Keep the main content within a readable width and use the spacing scale only: `xs`, `sm`, `md`, `lg`, `xl`. Interactive controls are at least 44px high. On larger screens, add breathing room rather than changing the information priority established by the Product Map and criteria.

## Elevation & Depth

ProudVault is mostly flat. Separate surface from background with a `border` and restrained shadow only where an element must be lifted above surrounding content. Avoid heavy, floating-card effects; hierarchy comes first from spacing, type, and contrast.

## Shapes

Inputs use the smaller `6px` radius for precise entry. Buttons and book cards use `12px` for calm, friendly grouping. Use the pill radius only for compact labels, never as the default shape for everything.

## Components

### Primary action

Use `button-primary` for one primary action available at a time. Its white text on blue background is the approved contrast pair. Keep a visible focus ring and a 44px minimum height on touch devices.

Traceability: PV-01, PV-03, PV-04.

### Text input

Use `input-default` for user-entered text. The visual treatment must leave room for a visible label and focus ring; placeholder text is supporting text, not a label.

Traceability: PV-03, PV-04, PV-07.

### Book card

Use `card-book` to group a book's identifying information. Preserve a readable title before decorative metadata, and allow text to wrap instead of becoming too small.

Traceability: PV-04, PV-05, PV-06, PV-07.

### Status message treatment

Use body text, an explicit text label, and an optional icon with sufficient contrast. Do not rely on green, red, or an icon alone to communicate a result; the exact behavior and message cases remain in `PRODUCT_PLAN.md`.

Traceability: PV-05, PV-07.

## Do's and Don'ts

- Do reserve primary blue for the single clearest action, and use a visible focus treatment for keyboard users.
- Do check contrast whenever a new foreground/background pair is proposed.
- Do let Thai titles and ISBNs wrap or use enough space to stay unambiguous.
- Do return to `PRODUCT_PLAN.md` when a visual question actually changes a page, flow, state, or behavior.
- Don't copy a gallery reference's logo, photos, brand voice, or complete layout.
- Don't add dashboard, social, recommendation, or sharing components from ProudVault's Non-goals.
- Don't use color alone for meaning, or placeholder text in place of a label.
- Don't write HTML, CSS, library choices, or component implementation details in this file.

หน้าตาของผลลัพธ์ที่ต้องได้

ใช้ template นี้เป็น output ที่ AI ต้องร่างให้ ไม่ต้องกรอกทุกบรรทัดเองตั้งแต่ต้น

---
version: alpha
name: [ชื่อ product]
description: [หนึ่งประโยค: visual identity นี้ช่วยผู้ใช้ในบริบทใด]
colors:
  primary: "#[hex]"
  on-primary: "#[hex]"
  background: "#[hex]"
  surface: "#[hex]"
  text: "#[hex]"
  text-muted: "#[hex]"
  border: "#[hex]"
  focus: "#[hex]"
typography:
  display:
    fontFamily: "[font stack]"
    fontSize: 1.5rem
    fontWeight: 700
    lineHeight: 1.25
  body:
    fontFamily: "[font stack]"
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 6px
  md: 12px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
components:
  [component-name]:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.text}"
    typography: "{typography.body}"
    rounded: "{rounded.md}"
    padding: 12px
---

## Overview

[บุคลิก ความรู้สึก ผู้ใช้ และบริบทที่ design นี้ต้องรองรับ]

## Colors

[บทบาทของสี และคู่สีที่ต้องผ่าน contrast]

## Typography

[ลำดับชั้น การอ่าน และข้อจำกัดของเนื้อหาจริง]

## Layout

[หลัก mobile/desktop, spacing และ touch target]

## Elevation & Depth

[ใช้ shadow, border หรือ tonal layers อย่างไร]

## Shapes

[radius และรูปทรงที่สม่ำเสมอ]

## Components

### [ชื่อ component]

[visual role, token, mobile consideration]

Traceability: [STORY-01, AC-01].

## Do's and Don'ts

- Do [กติกาที่ AI ต้องทำ]
- Don't [สิ่งที่ห้ามทำ]