From fca7991c8281267e0d1af7cd927a1b41e392c910 Mon Sep 17 00:00:00 2001 From: "codepress-dev[bot]" <202219725+codepress-dev[bot]@users.noreply.github.com> Date: Fri, 15 May 2026 04:26:08 +0000 Subject: [PATCH] Update DESIGN.md --- DESIGN.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 DESIGN.md diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..bdfc70a --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,40 @@ +# Design Guide + + + +SECTION 1: Primary Styling System +‣ Brand feel / mood: Dark, immersive demo aesthetic — a full-bleed menu library where a navy/black background, white type, and a single zoom-and-scale transform drive the personality. +‣ One-word system: Mixed. Aphrodite CSS-in-JS (`StyleSheet.create` + `css()`) is the library's authoring system, augmented by a SCSS-compiled CSS file in the demo and one hand-written plain CSS file (`Watermark.css`). +‣ Breakpoints: Custom min-width media queries declared inline in Aphrodite styles — `768px`, `1024px`, `1440px` (Menu.js / Nav.js); the Reactagram demo also uses a `max-width: 880px` collapse. + +SECTION 2: Other Styling Signals +‣ Aphrodite StyleSheet (CSS-in-JS): ~70%. +‣ Compiled SCSS / plain CSS files: ~20%. +‣ Inline `style={{...}}` props: ~10%. +‣ Evidence: `var styles = StyleSheet.create({ menu: { position: 'relative', overflow: 'hidden' } })` (Menu.js) +‣ Evidence: `className={css(styles.linkStyle) + " " + this.props.linkClassName}` (Nav.js) +‣ Evidence: `
` (demo/App.js) + +SECTION 3: Repo-Level UI Context +‣ Framework: React (15.6.1, class components, `React.PropTypes`). +‣ Language split: JavaScript (.js / .jsx only — no TypeScript). +‣ UI libraries: None. `react-router-dom` provides `Link`; `react-animations` provides `fadeInLeft` / `fadeInRight` keyframes consumed by Aphrodite. +‣ Pre-processors: SCSS via `node-sass` + `sass-loader` (used only by `src/demo/007-reactagram/src/App.scss`). CSS-in-JS: Aphrodite. +‣ State libraries: None — local `this.state` only. +‣ Color palette: No central token file. Library uses `#fff` for nav text, `rgba(255, 255, 255, 0.5)` for tagline, and a bundled background image (`assets/img/background.jpg`) as the menu surface. Demo uses background `#000`, panel `#252D3F`, sidebar `rgba(46, 56, 79, 0.85)`, image-container `rgba(28, 34, 47, 0.5)`, accent pink `#ff0084` (Watermark "deploy"). No CSS custom properties, no Tailwind config, no shadcn variables. +‣ Typography: `'Roboto Mono', monospace` for the demo shell and nav; `'Lato', sans-serif` (weights 100/300/400/700/900, loaded via Google Fonts `@import`) for the Reactagram demo. Scale is hand-tuned in px/em: `12px` tagline, `14px` body, `23px` company name, `2em` nav link at ≥768px, `2.5em` at ≥1440px. Conventions: `letterSpacing: '2px'` + `textTransform: 'uppercase'` on small labels; `fontWeight: '300'` on large nav links. +‣ Spacing & layout: No spacing scale. Ad-hoc px values (`marginBottom: '25px'`, `marginTop: '40px'`, `padding: '20px'`). Layout primitives are flexbox (`display: flex; alignItems: center`) with hand-set `paddingLeft` ramping by breakpoint (100/150/200 px). Container widths use viewport units (`100vw`, `90vw`, `100vh`) rather than fixed max-widths. +‣ Shape & elevation: Corner radius appears only once — `border-radius: 4px` on the Watermark chip. Elevation strategy is two ad-hoc box-shadows: `rgba(0,0,0,0.3) 0 0 10px 3px` on the scaled-down app, `0 10px 20px rgba(0,0,0,0.5)` on the reactagram image, plus hover-grow `transform: scale(1.1)` on filter tiles. No tonal-layer or shadow-scale system. +‣ Component patterns: + Menu wrapper (consumer API): `` — wraps children, scales the first child to `scale(0.8) translateY(-50%)` when active, applies a fullscreen background image. + Nav link: `StyleSheet.create({ linkStyle: { textDecoration: 'none', color: '#fff', fontWeight: '300', '@media (min-width: 768px)': { fontSize: '2em' }, '@media (min-width: 1440px)': { fontSize: '2.5em' } } })`, item wrapper sets `opacity: .7` → `:hover { opacity: 1 }`. + Small label / tagline: `{ color: 'rgba(255,255,255,0.5)', letterSpacing: '2px', textTransform: 'uppercase', fontSize: '12px' }`. + Overridable styling: every component accepts paired `xxxClassName` + `xxxStyle` props (`menuClassName`, `appClassName`, `navClassName`, `navItemClassName`, `linkClassName`, `companyClassName`, `navLinkStyle`) so consumers can layer their own classes on top of the Aphrodite hash. + +SECTION 4: Guidance for Downstream LLM +‣ Do author new styles with `StyleSheet.create({...})` + `css(styles.foo)` from `aphrodite`, matching the existing `var styles = StyleSheet.create({...})` block at the bottom of each component file. +‣ Do thread an optional `xxxClassName` (and where appropriate `xxxStyle`) prop through any new component so consumers can override its look — this is the repo's established extensibility contract. +‣ Do reuse the existing breakpoints (`768px`, `1024px`, `1440px`) as inline `'@media only screen and (min-width: …)'` keys inside the Aphrodite style object; don't invent new breakpoints. +‣ Don't introduce Tailwind, styled-components, CSS Modules, MUI, Radix, or shadcn/ui — none of them are installed and adding one would split the styling system further. +‣ Don't add new shadow recipes; reuse `rgba(0, 0, 0, 0.3) 0 0 10px 3px` for the scaled-app surface and `0 10px 20px rgba(0, 0, 0, 0.5)` for image-style elevation. +‣ Don't convert JS/JSX files to TypeScript or use hooks/functional refactors — the codebase targets React 15 with class components and `React.PropTypes`, so new code should match (`class X extends React.Component` + `propTypes`).