LME Flutter Skill — Build với lme_ui design system

AUTO-TRIGGER

Invoke lần đầu mỗi session khi:

• Project pubspec có lme_ui: dependency
• File Dart sắp edit có import 'package:lme_ui/lme_ui.dart'
• User nói: "build chat screen LME", "dùng Lme component", "code feature trong lsite/itg-mobile"
• User gửi link Figma kèm yêu cầu code Flutter UI cho project có lme_ui

KHÔNG dùng khi

• Project Flutter KHÔNG dùng lme_ui → dùng mobile-design skill
• Web → dùng frontend-design / kimi-render

Tư duy cốt lõi

KHÔNG tự build component nếu LME đã có.
KHÔNG hardcode color/font/spacing — luôn dùng LmeTheme.of(context) tokens.
KHÔNG dùng Material Icons — luôn LmeIcons.*
KHÔNG extend Material widget — chỉ compose.
LUÔN check pattern reference TRƯỚC khi code feature mới.

Workflow chuẩn (5 bước)

Bước 1 — RECON (đọc context)

Path quan trọng (cache vào memory mỗi session đầu):

• LME repo root: /Volumes/hai/lme-ui-flutter
• Component list: /Volumes/hai/lme-ui-flutter/lib/src/components/lme_*/README.md
• Patterns (cực giá trị): /Volumes/hai/lme-ui-flutter/example/lib/patterns/
• Demo pages: /Volumes/hai/lme-ui-flutter/example/lib/demo/lme_*_demo_page.dart
• Icon set: /Volumes/hai/lme-ui-flutter/lib/src/icons/lme_icons.dart (202 icons)
• Foundations: /Volumes/hai/lme-ui-flutter/lib/src/foundations/lme_*.dart
• Project rules: /Volumes/hai/lme-ui-flutter/CLAUDE.md

Đọc trước khi code:

1. Liệt kê file pattern liên quan: ls /Volumes/hai/lme-ui-flutter/example/lib/patterns/
2. Nếu pattern khớp use case → đọc full → copy adapt (NHANH HƠN build từ 0 rất nhiều)
3. README component nào sắp dùng → đọc props bảng để biết API chính xác

Bước 2 — PARSE FIGMA

Khi user gửi link Figma:

1. Extract fileKey + nodeId từ URL (figma.com/design/:fileKey/...?node-id=:nodeId → đổi - thành :)
2. Gọi mcp__claude_ai_figma__get_design_context với fileKey + nodeId
3. Đọc screenshot + structure
4. MAP NGAY mỗi element trong design → LME component:
   • Avatar tròn → LmeAvatar (.image / .text / empty + showDot/pinned)
   • List item chat → row tự build với LmeAvatar + LmeBadge.dot + tokens (LME KHÔNG có LmeChatTile sẵn)
   • Header với leading/trailing → LmeHeader
   • Tabs → LmeTabs + LmeTabItem
   • Bottom sheet → LmeBottomSheet.show + LmeBottomSheetHeader.close + LmeBottomSheetAction
   • Popover menu → LmePopoverMenu.show + LmePopoverMenuItem (anchor bằng GlobalKey)
   • Empty state → LmeEmpty + LmeEmptyIllust.*
   • Multi-select check → LmeCheckCircle
   • Chat input bar → LmeMessageInput (có sẵn reply preview, attach, send)
   • Keyboard toolbar → LmeKeyboardActions + LmeToolbarAction
   • Insert menu (sticker/file) → LmeInsertMenu.show
   • Tag pill → LmeTag (hoặc tự build nếu Figma khác)
   • Button → LmeButton
   • Input field → LmeInputTextField
   • Modal → LmeModal
   • Drawer → LmeDrawer
   • Dialog → LmeDialog
   • Toast → LmeToast
   • Status pill → LmeStatus
   • Switch / Radio / Checkbox → LmeSwitch / LmeRadio / LmeCheckBox
   • Date / Time picker → LmeDatePicker / LmeTimePicker / LmeCalendar
   • Stepper → LmeStepper / LmeStep
   • Walkthrough overlay → LmeWalkthrough
   • Swipe action row → LmeSwipeAction
   • Image preview → LmePreviewImage
   • Uploader → LmeUploader
   • Select dropdown / bottom sheet picker → LmeSelect
   • Breadcrumb → LmeBreadcrumb
   • Headline → LmeHeadline
   • Nav bar (bottom) → LmeNavBar

Bước 3 — CHECK ICONS

Trước khi code, đọc /Volumes/hai/lme-ui-flutter/lib/src/icons/lme_icons.dart (202 icons có sẵn).

Cheatsheet 10 icon hay dùng:

Không match? Grep trong lme_icons.dart hoặc check tools/config.mjs NAME_MAP (Japanese name từ Mishona set).

CẤM tuyệt đối Material Icons.* trong code mới. Chỉ 3 ngoại lệ legacy đã biết: format_bold/format_italic/format_strikethrough trong lme_keyboard_toolbar.dart.

Bước 4 — CODE (compose, never extend)

Skeleton chuẩn:

import 'package:flutter/material.dart';
import 'package:lme_ui/lme_ui.dart';

class MyScreen extends StatelessWidget {
  const MyScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final tokens = LmeTheme.of(context); // ← lấy tokens, KHÔNG hardcode

    return Scaffold(
      backgroundColor: tokens.colors.background,
      body: Column(
        children: [
          LmeHeader(title: 'Title'),
          // ... compose Lme components
        ],
      ),
    );
  }
}

Rules cứng:

• Mọi color → tokens.colors.* (CẤM Color(0xFF...) trừ khi pattern Figma đã pixel-perfect lock — copy cả block _kPageBg constants từ pattern reference)
• Mọi spacing → tokens.spacing.* (xs/sm/md/lg/xl/xxl/xxxl)
• Mọi font → tokens.typography.* (display/title/body/label)
• Mọi radius → tokens.radius.*
• Mọi icon → LmeIcons.*
• Component với onPressed nullable = disabled state (KHÔNG tạo disabled: bool riêng)

Khi LME không có sẵn (vd message bubble bóng chat):

• Tự build, nhưng dùng tokens hết — không hardcode
• Đặt trong widgets/ của feature, không global

Bước 5 — VERIFY

Trước khi báo "xong":

• flutter analyze pass
• Không còn Icons.* Material trong file mới (grep -n "Icons\." <file>)
• Không còn Color(0xFF...) hardcode (trừ pattern lock)
• Không extend Material widget (extends ElevatedButton/TextField/...)
• Không Platform.isIOS/Android trong UI
• Test trên device/simulator nếu có thể

Pattern reference đã verify (CẬP NHẬT KHI THÊM)

Khi build feature mới và không thấy pattern khớp → check lại ls /Volumes/hai/lme-ui-flutter/example/lib/patterns/ xem có pattern mới không. Nếu thật sự không có, build từ component README.

Common pitfalls (đã từng sai, đừng lặp)

1. ❌ Nhầm LmeList cho chat conversation list → LmeList là key-value list (form/profile), KHÔNG phải chat list. Chat list phải tự compose row.
2. ❌ Nhầm LmeMessageCreation cho 1-1 chat → đó là builder cho campaign message (compose nhiều message gửi hàng loạt).
3. ❌ Quên LmeTheme.of(context) ancestor — components cần MaterialApp wrap LmeTheme.light() ở root.
4. ❌ Wrap demo page trong MaterialApp thứ 2 — ko cần, gallery đã wrap rồi.
5. ❌ Resize LmeAvatar bằng SizedBox → dùng prop size: LmeAvatarSize.sm/md/lg.
6. ❌ Đoán tên icon → check /Volumes/hai/lme-ui-flutter/lib/src/icons/lme_icons.dart trước. VD: KHÔNG có systemInformation, đúng là LmeIcons.systemInfo / systemInfoFill.
7. ❌ Dùng LmeTabs mặc định cho > 4 tabs → set variant: LmeTabsVariant.scrollable cho 5-6 tab horizontal scroll.
8. ❌ LmeSwipeAction width 98 với label katakana 6 ký tự (vd "ブックマーク") sẽ wrap 2 dòng. Công thức: katakana CJK full-width ≈ 12px/char × N + padding 40 = min width. "ブックマーク" 6 chữ → cần ≥ 112, set width 120 an toàn (110 vẫn thiếu).

Project context (cập nhật khi đổi)

lsite-mobile

• Path: /Volumes/hai/lsite-mobile
• pubspec dep: lme_ui từ git ref build_phase_1
• LmeTheme: đã wrap ở lib/app/app.dart:19
• Feature đang code: chat (lib/features/home/presentation/)
  • tabs/chat_tab.dart — CHA, list conversations
  • page/messages/ — CON, detail page + widgets
• Pattern target: lme_message_list_pattern.dart (đã verify gần khớp)

Self-update rule

Mỗi khi học được điều mới về LME (component mới, pattern mới, pitfall mới, project mới dùng LME), cập nhật vào skill này, không chỉ memory cá nhân. Skill này là source of truth cho mọi session sau.

Section cần update khi:

• Phát hiện component LME mới chưa list ở Bước 2 → thêm vào bảng map
• Tìm thấy pattern mới giá trị → thêm vào bảng "Pattern reference"
• Sai một lần → ghi vào "Common pitfalls"
• Project mới adopt LME → thêm vào "Project context"
• Icon mapping mới hay dùng → thêm vào cheatsheet