Files

T

Antigravity Agent c24165b8bc refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조

에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게
[공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류.
문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인).

- Topic_Programming → Domain_Programming (내부 구조 보존)
- Topic_Graphic → Domain_Design
- Topic_Business → Domain_Product
- Topic_General → Domain_General
- _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning),
  Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing)
- 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서)
- 빈 폴더 정리 (memory/procedures)
- 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-11 11:05:56 +09:00

7.5 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

title

Style Registry

매 한 줄

"매 SSR streaming 시 CSS-in-JS 의 styles 를 HTML 에 inject 하는 mechanism". Next.js 13 App Router 의 useServerInsertedHTML hook 도입 — 매 streaming RSC render 도중 styled-components / emotion / @mui 가 generated CSS 를 <head> 의 inject. 2026 zero-runtime CSS (Vanilla Extract / Panda) 의 등장 으로 registry 의 less common, but legacy SC/emotion app 의 still required.

매 핵심

매 Why needed

CSS-in-JS = runtime styles: rules generated when component renders.
SSR: server renders HTML; client hydrates. Without registry → FOUC (flash of unstyled content) + hydration mismatch.
Streaming SSR: HTML chunks sent progressively. Styles must inject as components render, not at end.
App Router: useServerInsertedHTML provides hook into Suspense boundary stream.

매 Mechanism

Server: collect styles into sheet during render (per request).
Server: insert <style> tags into HTML stream via useServerInsertedHTML.
Client: hydrate — runtime takes over, no re-render needed.
Concurrency: per-request sheet (no global state pollution).

매 응용

styled-components in Next.js App Router.
Emotion in Next.js App Router.
@mui v5+ in Next.js.

💻 패턴

styled-components Registry

// app/lib/registry.tsx
'use client';

import React, { useState } from 'react';
import { useServerInsertedHTML } from 'next/navigation';
import { ServerStyleSheet, StyleSheetManager } from 'styled-components';

export default function StyledComponentsRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet());

  useServerInsertedHTML(() => {
    const styles = styledComponentsStyleSheet.getStyleElement();
    styledComponentsStyleSheet.instance.clearTag();
    return <>{styles}</>;
  });

  if (typeof window !== 'undefined') return <>{children}</>;

  return (
    <StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
      {children}
    </StyleSheetManager>
  );
}

Apply in root layout

// app/layout.tsx
import StyledComponentsRegistry from './lib/registry';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <StyledComponentsRegistry>{children}</StyledComponentsRegistry>
      </body>
    </html>
  );
}

Emotion Registry

// app/lib/emotion-registry.tsx
'use client';

import createCache from '@emotion/cache';
import { CacheProvider } from '@emotion/react';
import { useServerInsertedHTML } from 'next/navigation';
import { useState } from 'react';

export default function EmotionRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  const [{ cache, flush }] = useState(() => {
    const cache = createCache({ key: 'css' });
    cache.compat = true;
    const prevInsert = cache.insert;
    let inserted: string[] = [];
    cache.insert = (...args) => {
      const serialized = args[1];
      if (cache.inserted[serialized.name] === undefined) {
        inserted.push(serialized.name);
      }
      return prevInsert(...args);
    };
    const flush = () => {
      const prev = inserted;
      inserted = [];
      return prev;
    };
    return { cache, flush };
  });

  useServerInsertedHTML(() => {
    const names = flush();
    if (names.length === 0) return null;
    let styles = '';
    for (const name of names) {
      styles += cache.inserted[name];
    }
    return (
      <style
        data-emotion={`${cache.key} ${names.join(' ')}`}
        dangerouslySetInnerHTML={{ __html: styles }}
      />
    );
  });

  return <CacheProvider value={cache}>{children}</CacheProvider>;
}

@mui Registry

// app/lib/mui-registry.tsx
'use client';

import { AppRouterCacheProvider } from '@mui/material-nextjs/v15-appRouter';
import { ThemeProvider } from '@mui/material/styles';
import { theme } from './theme';

export default function MuiRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <AppRouterCacheProvider options={{ enableCssLayer: true }}>
      <ThemeProvider theme={theme}>{children}</ThemeProvider>
    </AppRouterCacheProvider>
  );
}

Pages Router (legacy) — _document.tsx

// pages/_document.tsx — Pages Router uses different mechanism
import Document, { DocumentContext } from 'next/document';
import { ServerStyleSheet } from 'styled-components';

export default class MyDocument extends Document {
  static async getInitialProps(ctx: DocumentContext) {
    const sheet = new ServerStyleSheet();
    const originalRenderPage = ctx.renderPage;
    try {
      ctx.renderPage = () =>
        originalRenderPage({
          enhanceApp: App => props =>
            sheet.collectStyles(<App {...props} />),
        });
      const initialProps = await Document.getInitialProps(ctx);
      return {
        ...initialProps,
        styles: [initialProps.styles, sheet.getStyleElement()],
      };
    } finally {
      sheet.seal();
    }
  }
}

Verifying SSR works

// 1. View source (Cmd+U) — should see <style> tags with rules
// 2. Disable JS in DevTools — page should still be styled
// 3. Check Network tab — no FOUC during page transition
// 4. React DevTools — no hydration mismatch warnings

매 결정 기준

상황	Approach
Greenfield 2026 Next.js	Tailwind / Vanilla Extract — no registry needed
Existing styled-components migration	Add StyledComponentsRegistry
Emotion-based codebase	EmotionRegistry pattern
@mui v5+	AppRouterCacheProvider (built-in)
Pages Router legacy	_document.tsx + sheet collection

기본값: greenfield → zero-runtime CSS (no registry). Existing CSS-in-JS → use library-recommended registry pattern.

🔗 Graph

부모: CSS in JS · SSR
변형: useServerInsertedHTML
응용: Styled Components v6
Adjacent: Streaming SSR · React Server Components — 경계 의식 · Hydration

🤖 LLM 활용

언제: SSR setup for CSS-in-JS, Next.js App Router migration from Pages, debugging FOUC / hydration mismatch. 언제 X: Tailwind / CSS Modules / Vanilla Extract — these are zero-runtime, no registry needed.

❌ 안티패턴

No registry → FOUC: styled-components SSR without registry shows unstyled HTML on first paint.
Global sheet (not per-request): cross-request style pollution / memory leak.
'use client' on registry but rendered at top level: marks entire tree as client — kills RSC benefit. Wrap deeply.
Forgetting clearTag(): duplicate styles inserted on each chunk.
Mixing registries: emotion + styled-components → two style systems, double bundle, conflicts.

🧪 검증 / 중복

Verified (Next.js docs app/building-your-application/styling, styled-components Next.js example, Emotion + Next.js guide).
신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — full canonical (registry mechanism + SC/Emotion/MUI patterns + Pages Router fallback)

7.5 KiB Raw Blame History