tt-adapt（tt 适应）

Context Check

1. Read .tt-impeccable.md from project root — confirms current fidelity tier, existing patterns, and constraints.
2. If absent, infer tier from codebase (mobile-first 390px = Strict TUX-native; dark #000000 desktop = TT Style).
3. Only run /tt-impeccable teach if the tier is genuinely ambiguous and matters for the adaptation.

Note the current fidelity tier and the target fidelity tier — adaptation may shift a surface between tiers, and this changes which constraints apply after adaptation:

Token values are fixed regardless of tier — load from tt-impeccable/reference/tokens.md as needed.

• Strict TUX-native → TT Style: moving a mobile product surface to a web/marketing context. The target unlocks uncapped spacing, display type scale, dark canvas, and expressive motion — but TUX token values and the neutral-first color rule still apply. Glassmorphism is opt-in, not a TT Style default — ask the user explicitly before introducing backdrop-filter: blur() surfaces; do not assume it because the tier changed.
• TT Style → Strict TUX-native: the reverse. Strip desktop patterns, cap spacing at 32px, enforce 390px canvas and safe area, remove glassmorphism if present.
• Same-tier adaptation (native → native web, or TT Style → responsive TT Style): constraints don't shift, only layout and interaction patterns are rethought.

Adaptation is not scaling. It is rethinking the experience for a new context while keeping TUX token fidelity and the TikTok design language intact.

Step 1: Assess the Adaptation

Understand the source

• What was this designed for? (390px native, desktop web, tablet?)
• What TUX patterns are already in use?
• What assumptions are baked in? (touch-only input? fixed-width canvas? no safe area?)

Understand the target

• Context: native mobile → web? web → wider viewport? web → mobile web?
• Input method: touch, mouse, keyboard, or all of the above?
• Viewport range: what widths need to work?
• Usage context: same users on a different device, or a different user context entirely?

Identify the adaptation challenges

• What TUX patterns don't translate directly? (bottom tab bar → web nav, safe area → scroll padding)
• What interactions need rethinking? (touch swipe → click/keyboard, hover states)
• What layouts need restructuring? (single-column → multi-column, or vice versa)
• What TUX tokens stay the same regardless? (all of them — tokens never change by context)
• Color restraint is non-negotiable across all contexts: even if the target context allows more design freedom (TT Style), Primary (brand red) stays on at most one distinct element type per screen, and media surfaces always use neutral overlays. Never introduce colored image/video tints during adaptation.

TUX tokens are non-negotiable across all contexts. Colors, spacing values, radius, shadow, and typography come from the same token tables whether the surface is native or web. The layout adapts; the tokens do not.

Step 2: Plan the Adaptation

Strict TUX-native → web (TUX-inspired or TT Style)

The most common case. Preserve TUX hierarchy; adapt chrome patterns.

Fidelity target matters here. If the target is a TUX-inspired product web surface (same product, wider screen), the Strict TUX-native constraints still mostly apply. If the target is a TT Style web/marketing surface (brand hub, campaign page, landing page), the endpoint has more latitude: dark canvas preferred, uncapped section spacing, display type scale for hero text. Determine which before adapting. Do not introduce glassmorphism during this step without first asking the user — it is opt-in even in TT Style.

In either case: TUX token values are unchanged. Neutral-first color rule applies. Media overlays remain neutral (black-alpha / white-alpha only).

Layout changes:

• Page max-width container: wrap content in max-width: 480px; margin: 0 auto at minimum; wider at ≥768px up to ~960px depending on content density
• Page horizontal padding: stays 16px on mobile; may increase to 24–32px on wider viewports
• Single-column content: stays single-column unless there is a clear content reason to split

Navigation changes:

• Bottom tab bar → top navigation bar or left sidebar (keeping same token values)
• Navigation items: same text, same icons, same active state colors — only position changes
• If sidebar: use UI/Page/Flat 2 background (#F8F8F8 light / #1E1E1E dark); width 240–280px

Interaction changes:

• Add :hover states (web users have cursors)
• Keep :focus-visible (keyboard users)
• Do not remove touch support — many desktop users have touch screens
• Swipe gestures: add keyboard / click equivalents for every swipe action
• Bottom sheets: may remain as centered modals on wide viewports (use L2 container radius: 16/26px)

Content changes:

• Safe area spacers: replace with scroll padding or viewport-relative padding
• Status bar spacer: not needed on web; remove or replace with 0

Anti-patterns to avoid during this adaptation:

• Adding three-column layouts, persistent content sidebars, or floating toolbars that have no TUX grounding
• Using hover as the primary way to access functionality
• Replacing TUX token values with generic web design values ("I'll use a softer blue for links")
• Making the web version feel like a different product from the TikTok app
• Adding borders to containers because "the web version needs more structure" — adapt layout, not separation language. Use UI/Page/* surface layering to define sections; borders are a last resort in both tiers

TUX-inspired web → tighter mobile web

Making a web-adapted surface work well on 390px.

Layout changes:

• Remove multi-column: stack to single column
• Remove persistent sidebars: collapse to hamburger or bottom nav
• Page horizontal padding: fix at 16px regardless of what it was on desktop

Interaction changes:

• All touch targets: ≥ 44×44px — check every icon button, inline link, and list row
• Remove hover-dependent functionality: every action accessible by tap
• Add safe area insets: env(safe-area-inset-top/bottom) in page shell
• Add viewport-fit=cover to meta viewport

Content changes:

• Ensure content clips slightly at viewport bottom for scrollability signal
• List padding rule: first cell top gap = cell-to-cell gap + 8px

Same-tier adaptation (most common case)

Adapting within the same tier — adding responsive breakpoints, handling wider mobile/tablet viewports, or making an existing TT Style page work across viewport widths. Constraints don't shift; only layout and interaction patterns are rethought.

TUX-native → wider viewport (tablet, larger mobile): start from the 390px layout and add breakpoints only where the layout actually breaks.

• Tokens never change at any breakpoint
• Component dimensions never change (button heights, input height, nav bar height)
• Font sizes stay fixed px — no fluid scaling
• Minimum touch targets stay 44×44px

TT Style → narrower viewport: reverse the desktop-first layout.

• Collapse multi-column editorial grids to single column at ≤768px
• Switch from sidebar nav to hamburger or bottom nav
• Horizontal padding: 80–120px desktop → 24px mobile
• Preserve dark canvas and TUX token values throughout
• All motion still needs prefers-reduced-motion fallback

Adding responsive breakpoints to a TUX-native surface

When a strict TUX-native design needs to work on a tablet or larger mobile.

Approach: start from the 390px native layout. Add breakpoints only where the layout actually breaks — not based on device names.

/* Base: 390px native — always correct */
.container { padding: 0 16px; }

/* Tablet / wider mobile — add when content has room to breathe */
@media (min-width: 600px) {
  .container {
    padding: 0 24px;
    max-width: 560px;
    margin: 0 auto;
  }
}

/* Web adaptation — wider canvas */
@media (min-width: 960px) {
  .container {
    padding: 0 32px;
    max-width: 800px;
  }
}

What does NOT change at any breakpoint:

• TUX token values (colors, radius, shadow)
• Component dimensions (button heights, input height, nav bar height)
• Font sizes (TUX uses fixed px — no fluid scaling)
• Minimum touch target sizes

Step 3: Implement

Work systematically through the adaptation plan. For each changed pattern, verify:

1. TUX tokens are intact — no new hard-coded values introduced
2. Hierarchy is preserved — content still leads, chrome still supports
3. Interaction completeness — all states exist in the new context (hover added for web, touch preserved for all)
4. Accessibility — focus rings, touch targets, and ARIA roles still correct after layout changes

Input method detection

For web adaptations that need to support both touch and mouse:

/* Touch: coarse pointer — keep generous targets */
@media (pointer: coarse) {
  .btn { min-height: 44px; }
}

/* Mouse: fine pointer — hover states make sense */
@media (hover: hover) and (pointer: fine) {
  .btn:hover { opacity: 0.85; }
  .list-row:hover { background: var(--tux-shape-neutral-4); }
}

Safe area handling

Required on any surface that might run on a real mobile device (native web, PWA, in-app browser):

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

.page-shell {
  padding-top: env(safe-area-inset-top, 44px);
  padding-bottom: env(safe-area-inset-bottom, 34px);
}

.tab-bar {
  padding-bottom: max(34px, env(safe-area-inset-bottom));
}

Step 4: Verify

• TUX token values unchanged across all viewport sizes
• All interactions work by touch AND by mouse AND by keyboard
• Touch targets ≥ 44×44px at every breakpoint
• No hover-only paths to core functionality
• TUX hierarchy (content-first) preserved at all viewports
• TikTok Native Test passes: still feels like TikTok, not a generic web app with TikTok colors
• Safe area insets applied wherever the surface may run on a phone
• No anti-patterns introduced during adaptation
• Color restraint maintained: Primary appears on at most one distinct interactive element type per screen in the adapted surface
• No colored (red or teal) overlays or tinted placeholders introduced on image/video surfaces during adaptation

Test on at least one real device per target context. DevTools emulation misses keyboard appearance, actual touch behavior, and safe area edge cases.

Never

• Change TUX token values during adaptation — the tokens are fixed regardless of context
• Use hover as the only path to any action — always provide a touch/keyboard equivalent
• Add desktop patterns (floating sidebars, three-column content grids, right-click menus as primary UI) without TUX grounding
• Make the web version feel like a different product from the TikTok app
• Skip input method detection — assume both touch and pointer are possible on modern devices
• Remove safe area handling to "simplify" — it breaks on real hardware
• Introduce colored tints (red, teal) on image or video surfaces during adaptation — neutral overlays only, regardless of context
• Treat TT Style as "anything goes" — TUX token values, TikTok Sans, and neutral-first color restraint still apply