Loading
Loading
/library · the docs, as shipped
The docs live with the code they describe — on this site and across every build. The reading room renders this repo's system documents whole from the build, then the other builds' own docs below them; the GitHub index carries the design systems and the doc collections — the repos where the docs are the point — with the design-system folders downloadable as zips, built in your browser; and the sites guide at the bottom says what every one of my sites runs on. No number was typed by hand.
01 / Reading room
design-system.md · 127 lines · 6.3 KB · source ↗
The receipt for how this site looks and moves: one ink on one paper, two typefaces with fixed jobs, motion that is always on except where it must answer to the visitor. Every value below is copied from the shipped files — the :root block and html.dark in src/app/globals.css, the html.uiux scopes, and src/app/fonts.ts — not from a design file that drifted.
| File | Role |
|---|---|
src/app/globals.css | :root tokens (light), html.dark, dev-site rules, motion tokens |
src/app/uiux/uiux.css | The editorial paper theme, scoped to html.uiux |
src/app/fonts.ts | Archivo (--sans) and Fragment Mono (--mono) declarations |
src/components/ThemeToggle.tsx | The theme state the tokens respond to |
src/components/Cursor.tsx | The pointer — draws only --fg/--bg, so themes re-ink it for free |
The whole site is --fg on --bg. Nothing picks a raw hex outside the :root blocks; accents, lines, softs and hovers are all declared once here and consumed everywhere, which is why a theme change re-inks the pointer, the chips, the hints, the swatches — everything — without a single special case.
| Token | Light | Dark | Job |
|---|---|---|---|
--bg | #ffffff | #0f0f11 | the paper |
--fg | #18181b | #ededf0 | the ink |
--muted | #5c5c66 | #9a9aa3 | the whisper (secondary text) |
--line | #e4e4e9 | #26262c | hairline rules |
--line-strong | #c9c9d1 | #34343d | visible edges (phone nav bar) |
--soft | #f6f6f8 | #1a1a1f | filled wells (code, table heads) |
--green | #15803d | #3fb950 | live status only — never brand |
--accent | #ea580c | #fb923c | UI/UX portfolio accent + its navbar pill |
--accent-dev | #2563eb | #60a5fa | the dev portfolio's blue |
--accent-contrast | #ffffff | #181818 | text on accent fills |
--btn-solid-hover | #35353b | #d6d6dc | solid button hover fill |
--header-bg | rgba(255,255,255,.92) | rgba(15,15,17,.9) | the sticky header's only glass |
color-scheme is set per theme (light / dark) so UA chrome — scrollbars, form controls — follows along. Status dots stay green on purpose: they mean "live", not "brand".
:root, the default.html.dark, toggled in the navbar, system preference by default, persisted in localStorage, applied pre-paint by the inline script in layout.tsx so there is no flash.html.uiux scope: the editorial portfolio defaults to light even on dark-OS machines (paper #F6F3EE, ink #1B1D22, mute #6B685F, line #DDD7CC; dark #141518 / #ECE8DF / #A09C92 / #2B2D33). :not(.dark) in the selectors lets the toggle win when a visitor flips it.Per-project accents live outside the token table on purpose: rows and case pages set --pa-light / --pa-dark inline (Taar/Sutra navy #1F2A44, Ghar terracotta #A63D1F), and uiux.css resolves them to --pa per theme. Both portfolios share the same accent patterns, so recoloring a portfolio is a one-line change — the discipline the token system buys.
Archivo (--sans) is the voice. One variable family with the width axis kept live (wdth 62..125, declared in fonts.ts): display type runs expanded at 125, body text runs normal width. The axis is a design material here, not a fallback.
Fragment Mono (--mono, weight 400 only) is the readout voice: meta lines, section indexes, years, statuses, counters, table heads — and the custom cursor's chips and hints. Everything quiet and factual on the site is Fragment Mono. The stacks carry the real font first and the family name second (var(--font-display), 'Archivo', system-ui, sans-serif) so the system falls back gracefully.
Scale discipline: display sizes are clamped, never fixed — the meta pages' h1 runs clamp(2.4rem, 6vw, 3.6rem); section titles and body sizes step down from there. Weights stay in the 400–700 band.
The philosophy: motion is communication, not garnish, and it runs for every visitor — Lenis inertial scrolling, split-text reveals, the scroll progress hairline, 420ms accordion folds. The tokens (:root):
| Token | Value | Job |
|---|---|---|
--ease-apple | cubic-bezier(0.16, 1, 0.3, 1) | the house easing — expo-out, fast start, long settle |
--ease-out | cubic-bezier(0.22, 1, 0.36, 1) | general transitions |
--press-scale | 0.97 | touch-down feedback on .btn, pills, the theme toggle |
--dur-micro | 120ms | micro-interactions (press, chevron, hover tints) |
The one exception proves the rule: the custom pointer honors the OS reduced-motion request — which used to silently hide it from visitors with "Animation effects: Off", the "nah cant see any diff" report. Since [1.4.7] the footer Cursor: auto / on / off toggle is the escape hatch: on overrides the OS, off forces native, auto (default) follows it. The label says "Cursor" because that is what it scopes to. Everything else stays always-on by design.
:active scale tovar(--press-scale) reads as acknowledgment, not decoration.
drops its blur and goes opaque.
(--line: #86868f under the contrast query).
makes sections 01–03 true at once.
parallax noise. Flat and fast on purpose; the Apple UX kit contributed the discipline, not the skin.
If you build on this repo: consume tokens, never raw hex; keep new motion on the two easings; keep status green for "live"; keep Fragment Mono for readouts. If you change a token, the CHANGELOG entry is the receipt — every version ships dated.
Shipped with [1.4.9]. Companion doc: custom-cursor.md (the pointer system).
custom-cursor.md · 193 lines · 10.4 KB · source ↗
The site-wide pointer: it replaces the native cursor on every route, and the hover guidance (chips, hints) rides with it. Shipped in two commits — ef42f9b ([1.4.6], site-wide replacement + hints riding the pointer) and 60ca4c6 ([1.4.7], the footer motion toggle). This doc describes the system as it actually behaves in src/, not as planned.
| File | Role |
|---|---|
src/components/Cursor.tsx | The engine: one rAF loop, all state, the portal |
src/app/cursor.css | The look, the cursor: none contract, field exemption |
src/components/MotionToggle.tsx | The preference (auto/on/off) + motionPref() |
src/components/Footer.tsx | Toggle mount (dev site footer, bottom row) |
src/components/uiux/Footer.tsx | Toggle mount (/uiux credit line) |
src/app/globals.css | .motion-toggle styles (a footer link that is a <button>) |
src/app/layout.tsx | Mounts <Cursor /> globally (line ~107) |
| Situation | Pointer behavior |
|---|---|
| Default | 6px ink dot tracking 1:1 + 32px wireframe square trailing on a lerp |
Over links/buttons (a, button, [role="button"], summary) | Ring wraps the dot — ring scale 1.45, opacity 0.9; dot shrinks to 0.6 |
Over [data-cursor] rows (project rows: data-cursor="View") | Dot+ring fade out; a filled ink chip with the label replaces them, centered on the pointer |
Over [data-hint] CTAs | A small ink hint caption rides beside the pointer ("Switch theme", "Opens PDF", "Pre-written answers · runs locally") |
| Mouse press | Dot scales 1.6×, ring squeezes to 0.85×, ring opacity 0.4; the hint stays up (flicker on click reads as a glitch) |
Over form fields (input, textarea, select) | Custom cursor fades out (.is-out), native I-beam returns — typing needs it |
| Pointer leaves the window / window blurs | Whole cursor fades out; returns on pointermove |
| Touch devices | Never activates — native behavior everywhere, by design |
Current hint inventory: ThemeToggle ("Switch theme"), Header resume ("Opens PDF"), AskOmkar pill ("Pre-written answers · runs locally"), /uiux Nav ("Dev portfolio", "Opens mail app", "LinkedIn · new tab"), /uiux footer ("Live site · new tab") and the /uiux contact CTAs.
The engine runs only when all of these hold, re-checked live:
matchMedia('(hover: hover) and (pointer: fine)') matches — coarse pointers bail before anything else happens.'off' forces native; 'auto' follows the OS (prefers-reduced-motion: reduce bails); 'on' overrides the OS.On activation it adds html.ux-cursor-on; cursor.css turns that into cursor: none !important on body * (inside the same media query, so the CSS and JS gates can never disagree). The class is removed on teardown — flipping the toggle or unmounting restores the native cursor without a reload.
Every frame the loop runs document.elementFromPoint() at the raw pointer position and re-derives all state from the element it returns. No hover state is ever cached from pointermove/pointerover events.
Why: this is a Lenis (inertial scroll) site. The pointer stands still while the page glides under it; pointer events stop firing; any event-cached state (a "View" chip, a hint) stays painted over content that has already scrolled away. Per-frame hit-testing is exactly what the browser does for :hover, and it costs one hit test per frame. Consequences that fall out of it for free: a hint dies the instant its CTA scrolls away, gets covered, or unmounts mid-hover (a zero-sized getBoundingClientRect also triggers setHint(null) for SPA swaps).
Position bookkeeping:
tx/ty — raw pointer (pointermove feeds coordinates only)dx/dy — dot, lerp 0.6 (near-instant)rx/ry — ring/chip/hint, lerp 0.18 (the lag is the design)vel = clamp((tx - rx) * 0.22, ±12) — ring rotates-5° + vel, chip rotates -2° + vel * 0.4
All four are aria-hidden, position: fixed in a body portal (z-index: 999, above the header at 100 and the AskOmkar pill/panel at 90/91) so no ancestor transform can offset them and no shell scoping can hide them.
var(--fg)), centered by −3px margins, 1pxvar(--bg) halo so it stays readable on ink surfaces (hovered inverted buttons). Rasterized at 2× (a 12px element with a 2px halo) and scaled 0.5 in the JS transform — see "Anti-aliasing" below.
opacity 0.55. Trails on the slow lerp with the velocity lean. Rasterized at 2× (64px element, 2px border, 8px radius) and scaled 0.5 in the JS transform — see "Anti-aliasing" below.
[data-cursor] label. Filled ink, Fragment Mono(--mono set explicitly — portal children sit outside every shell scope, so shell-scoped font vars silently resolved to nothing once), 0.62rem uppercase. Centered on the pointer using its measured offsetWidth/ offsetHeight (re-measured on every text change): a fixed margin hangs the label off-side the moment the text is wider than ~28px.
[data-hint] caption. Filled ink, 0.56rem mono uppercase,entrance rise via the translate property (pure translation, safe next to the JS transform). Anchored to the pointer, not the element box — on wide CTAs an element-anchored caption floats far from where the visitor is looking and reads as nobody's annotation.
hx = rx + 18; if hx + hintW > vw - 12: hx = rx - hintW - 18 // right-edge flip
if hx < 12: hx = 12 // hard clamp
hy = ry + 20; if hy + hintH > vh - 12: hy = ry - hintH - 16 // floor flipvw/vh are read from window.innerWidth/innerHeight every frame. The hint is suppressed while a [data-cursor] chip is active (the chip already announces the row) and while the pointer is over a form field.
The ring used to land at 1.45× the pointer position over links: the CSS individual scale property composes before transform, so a scaled element renders at scale × its translated position. Fix: scale is part of the translate3d(...) scale(...) string written per frame. Targets — dot: 1.6 pressed / 0.6 over links; ring: 0.85 pressed / 1.45 over links; chip: 1 in label mode / 0.4 otherwise.
The dot and ring are tiny composited boxes animated at fractional pixel offsets and rotations every frame — at their raw sizes the edges stair-step on 1×-DPR screens, worst on the ring's 1px corner arcs. Fix: supersample. cursor.css declares both at twice their visual size (dot 12px + 2px halo, ring 64px + 2px border + 8px radius + 2px halo) and Cursor.tsx writes scale(visual × 0.5) into the per-frame transform (const SS = 0.5). The compositor then resamples a doubled raster at every fractional offset and rotation, so edges render smooth. The scale lerp still works in visual units (press 1.6×, link 1.45×, squeeze 0.85× are unchanged); the factor folds into the written transform only. Chip and hint are text and stay 1:1 — glyphs are already anti-aliased by the font rasterizer, and scaling them down would blur them.
The site's motion philosophy is "always on" (Lenis, reveals, progress bar run for everyone), but the pointer was the one piece honoring the OS reduced-motion request — which silently hid it, and every hint, from visitors whose OS has "Animation effects: Off" (Windows) or Reduce Motion (macOS/iOS), with no way to opt in. That was the "nah cant see any diff" report. MotionToggle is the escape hatch:
auto → on → off, stored in localStorage('motion-pref')(motionPref() defaults to 'auto' on nothing/invalid/blocked storage).
window event 'motion-pref'; Cursorkeeps that in React state, so the effect tears down / re-inits live — no reload. Unmounting removes the flag and the native cursor returns.
scopes to the pointer, the only motion that consults the OS preference.
.motion-toggle in globals.css) next to"Back to top ↑" on the dev site and in the /uiux credit line.
Colors are only var(--fg) / var(--bg) — the pointer re-inks itself with every theme (light, dark, the /uiux paper theme) for free. The 1px var(--bg) halo on dot/ring/hint keeps ink readable where it crosses ink.
Scripts live in scripts/ and are tracked in git (since [1.5.4] — they used to be gitignored and were rewritten from scratch every session) and run against Playwright/chromium with real mouse simulation:
| Script | Checks | Notes |
|---|---|---|
verify-cursor-live.py | 30 (C1–C12) | States, flips, press, chip centering; the floor-flip case is made deterministic by spoofing window.innerHeight via Object.defineProperty |
verify-motion-toggle.py | 8 | Runs against the live deployment: reduced-motion OS reproduces the "no diff" report (T1), one click turns the pointer on live (T2–T3), choice survives reload (T4), "off" hands back native (T5), defaults untouched (T6–T7), touch stays native (T8) |
verify-askomkar.py | 13 | Chat panel behavior under the cursor system |
smoke-chat-cursor.py | 6 | Cross-checks including log scroll pinning |
Evidence screenshots: download/cursor-evidence/ (incl. the live-site before/after pair for the reduced-motion fix).
0.5 in the JS transform: anti-aliased edges at every fractional offset and rotation, identical geometry (see "Anti-aliasing" above).
ef42f9b — site-wide replacement (the native pointer used topop back over global chrome), hints anchored to the pointer with edge/floor flips, chip measured centering, portal font fix.
60ca4c6 — footer motion toggle; the gate treats an explicitvisitor choice as the authority over the OS.
README.md · 197 lines · 14.3 KB · source ↗
new/)Single Next.js 16 app hosting three faces of the same person, deployed as one Vercel project:
| Route | What it is | Accent |
|---|---|---|
/ | Developer portfolio (projects, skills, experience) | Blue |
/uiux | UI/UX portfolio — editorial index (Taar / Ghar / Sutra, how I work, also shipped) | Per-project |
/uiux/taar | Case study 01 — fashion e-commerce redesign | Taar navy #1F2A44 |
/uiux/ghar | Case study 02 — Pune tiffin app | Ghar terracotta #A63D1F |
/uiux/sutra | Case study 03 — checkout + design system | Taar navy #1F2A44 |
/uiux/relay/prototype | Relay case study — live clickable React prototype (legacy stage) | Relay palette (pine/gold) |
/now | The dated present — building, looking for, listening, reading | — |
/colophon | The maker's receipt — type, ink, motion, machine | — |
/library | The docs, as shipped — system docs rendered from the repo at build time + the file collections | — |
/creative | Slot for the creative version — navbar pill hidden while it's in dev | — |
Dark mode: toggle in the navbar, system preference by default, persisted in localStorage, no flash.
npm install # install
npm run dev # dev server (port 3000)
npm run build # production build
npm start # serve the production build
npm run lint # eslint
npm run typecheck # tsc --noEmitThe project uses npm (package-lock.json). Vercel detects npm automatically — nothing to configure.
You have a separate creative portfolio build and want it reachable from the navbar here (and vice versa) without a second Vercel project. A /creative route is already reserved, and the Creative navbar pill is written and ready — but hidden while the creative build is still in development. To re-enable it, restore the pill block in src/components/Header.tsx (marked with a NOTE comment; its .header-creative styles are still in globals.css). Pick one option:
Best if the creative version is (or can be) a Next.js App Router project.
app/ routes into src/app/creative/ (its page/layout/components become src/app/creative/page.tsx, src/app/creative/layout.tsx, …).src/app/creative/.globals.css, import it from src/app/creative/layout.tsx — keep class names prefixed or in a layer so it can't clash with the base site.public/creative/….src/app/creative/page.tsx (this placeholder) when the real page lands.import Link from 'next/link';
<Link href="/" className="your-pill-class">Developer</Link>npm run build — everything ships in one deployment at the repo's Vercel root.Pros: shared theme toggle + analytics, native routing, one install, one build. This is the cleanest shape.
public/Best if the creative version is Vite/SPA or otherwise hard to port.
npm run build with base: '/creative/'; Next: output: 'export' with basePath: '/creative' and trailingSlash: true).public/creative/ so it contains index.html plus its hashed assets.next.config.ts:async rewrites() {
return [
{ source: '/creative', destination: '/creative/index.html' },
{ source: '/creative/:path*', destination: '/creative/:path*' },
];
}<a href="/">Developer</a>.Pros: zero porting. Cons: two build pipelines, its JS/SEO is whatever the export gives you.
src/components/Header.tsx — hidden until the creative build ships, see note above) and the Developer button in the creative build's header are the two-way pair. Keep the labels symmetrical so users always know where they are.old/ (previous site) + new/ (this project).new.npm install, npm run build). No env vars needed.omkardile.is-a.dev stays pointed at this project.liquidGlassAppBase in src/data/site.ts. When the old apps move (different domain, or ported into old/ under another deployment), update that single line.public/case-studies/*.pdf, linked as /case-studies/<app>-case-study.pdf.All text, projects, skills, experience and socials live in src/data/site.ts (split into the dev projects/capabilities/experience, the design-side uiux export, and the full relay case study #1). Edit there, not in the pages.
The UI/UX case studies (Taar, Ghar, Sutra) live separately in src/data/uiuxProjects.ts — see the next section.
| # | Project | Status | Links on card |
|---|---|---|---|
| 01 | SSShopee — Retail ERP + Storefront | Live (one project, two apps) | Management app · Customer storefront · GitHub (ERP) |
| 02 | ServePoint — Café Operations Platform | Live | Live app · GitHub |
| 03 | PatelNetworks — Client E-commerce Platform | Live (client project) | Live site |
| 04 | tech // site — Technology Web Platform | Live | Site · GitHub |
| 05 | HandOff | Live product · public beta v1 · maintained | GitHub · Release beta.v1 |
| 06 | Bandwidth Bandit | Live (Android) | GitHub |
| 07 | Aether Weather App | Live | App · GitHub |
| 08 | AI Recipe Generator | Live (Google Gemini) | App · GitHub |
| 09 | Online Car Service Station | Academic — PG-DMC major project | Admin panel |
| 10 | Full-Stack Food Ordering App | In development | — |
| 11 | Real-Time Chat App | In development | — |
Content rules enforced in src/data/site.ts: every status, stack and link is verified against the live deployment or the project's public repository before publishing. GoldDrip was removed from the portfolio (owner request); the old SSShopee Render URL (shubhamsupershopee.onrender.com) is retired everywhere in favor of the Vercel admin URL. Project facts and the reasoning behind each entry are documented in decisions.md and technical-documentation.md; maintainer workflows live in help.md.
A project card carries one or more labeled links via the links array (single-link cards keep the whole-card hit target; multi-link cards render one anchor per destination, e.g. SSShopee's two applications).
Relay case study assets: public/work/relay/ (cover, diagrams, screens) — sourced from the owner's original upload (integrated into the site; the upload was removed from the repo afterwards). The live prototype is the owner's relay-prototype.jsx vendored as src/components/RelayPrototype.jsx (only change: "use client" directive).
src/data/uiuxProjects.ts)/uiux is a data-driven editorial portfolio: one index page plus three case-study pages sharing a single template (src/components/uiux/CaseStudyLayout.tsx). Copy rule: every sentence is ported verbatim from the project's own sources — the coded apps' README/CHANGELOG (upload zips) and the approved case-study copy in src/data/site.ts. No invented numbers, no quoted metrics, no research results that don't exist yet.
uiuxProjects in src/data/uiuxProjects.ts: slug, number, title, tagline, status (In progress / Complete), accent + accentDark (AA-lightened for dark mode), problem (two lines for the index row), role[], tools[], the three URL fields, tryIt, and sections — nine of them, in order: The problem · Research · Who it's for · Flow · Wireframes · Design decisions · Visual system · Usability test · Build & next.src/app/uiux/<slug>/page.tsx — copy one of the existing three; it only resolves the entry + per-route metadata (title, description, canonical, per-page OG + twitter pointing at /og/uiux-<slug>.png — render it with scripts/gen-og-images.py) and the prev/next neighbours. If the app runs on this site, also add src/app/uiux/<slug>/prototype/embed/page.tsx (copy Taar's; a chrome-free noindex stage) and fill prototypeUrl + prototypeEmbedUrl.src/app/sitemap.ts.Section content is a list of typed blocks the renderer already understands: paragraph, list (ordered/unordered), hypotheses, table, personas, flow, wireframes (inline SVG art — add a drawing to WireframeArt.tsx), decisions (title / rationale / trade-off), swatches, typeSpecimen, rules, slot.
Deploy each app separately (Vite → Vercel, no config), then fill the placeholders at the top of its entry in src/data/uiuxProjects.ts:
prototypeUrl: '', // deployed app URL or an internal /uiux/<slug>/prototype route — empty = "Try it" is hidden
prototypeEmbedUrl: '', // chrome-free stage for the DeviceFrame iframe (defaults to prototypeUrl)
figmaUrl: '', // Figma share link — empty = the "Design file" section is hidden
repoUrl: '', // GitHub — empty = the button is hiddenEmpty means hidden — the site never renders "link pending". The "Try it" embed is a 390×844 DeviceFrame (aspect-ratio reserved, no layout shift, sandboxed iframe that mounts only near the viewport on viewports ≥768px; phones get a poster + "Open prototype" button).
Sections whose evidence isn't collected yet stay honest: a { type: 'slot' } block renders a dashed placeholder in development and disappears from the production build; a table with filled: false renders the dashed skeleton in development and one quiet "Research in progress" line in production. And since [1.5.4]: a section made only of unfinished evidence collapses entirely in production (empty headings read as broken pages) and the surviving sections renumber 01..N. Development keeps everything. Keep the In progress status tag until the owner flips it.
Applied from the owner's Apple UX Design System reference document — the discipline, not the skin:
.btn, nav pills and the theme toggle scale to 0.97 on :active (100ms ease-out).--press-scale, --dur-micro in :root.scroll-behavior: smooth + scroll-padding-top so anchors land clear of the sticky header. Site motion — Lenis, reveals, the progress hairline — is always enabled for every visitor; the one exception is the custom pointer, which honors the OS reduced-motion request with the footer Cursor: auto / on / off toggle as the explicit override ([1.4.7] — see custom-cursor.md).--bg/--fg/--muted/--line/--soft/--accent), with color-scheme set per theme./ wears dev blue (--accent-dev, light #2563eb / dark #60a5fa). Site chrome keeps the classic orange for the /uiux switch pill, but the /uiux portfolio pages themselves run the editorial paper theme (html.uiux scope: paper #F6F3EE / ink #1B1D22 / mute #6B685F / line #DDD7CC, dark #141518 / #ECE8DF / #A09C92 / #2B2D33) with per-project accents — pages set --pa-light/--pa-dark inline and uiux.css resolves them to --pa (Taar/Sutra navy, Ghar terracotta). Both portfolios share the same accent patterns, so recoloring a whole portfolio stays a one-line change. Status dots stay green on purpose — they mean live, not brand.src/
app/
page.tsx # developer portfolio
uiux/uiux.css # editorial design system (scoped to .ux-shell)
uiux/page.tsx # UI/UX portfolio index (hero, work rows, principles, also shipped)
uiux/taar|ghar|sutra/page.tsx # case studies 01–03 (data-driven template)
uiux/relay|taar|sutra/prototype/ # legacy live prototype stages (site chrome)
creative/page.tsx # placeholder slot for the creative version
now/page.tsx # the dated present (building / looking for / listening / reading)
colophon/page.tsx # the maker's receipt (type, ink, motion, machine)
library/page.tsx # the docs, as shipped — build-time rendered + file collections
layout.tsx # root: metadata, JSON-LD, no-flash theme script, analytics
sitemap.ts, robots.ts, not-found.tsx, icon.svg
components/
uiux/ # UiuxShell (fonts + chrome), Nav, Footer, ProjectRow,
# CaseStudyLayout, blocks.tsx, DeviceFrame, WireframeArt
Header (client, pathname-aware — hides on the four /uiux chrome routes),
Footer, ThemeToggle, SmoothScroll, ScrollReveal, MotionCraft, RelayPrototype
data/
site.ts # dev portfolio + legacy uiux content
uiuxProjects.ts # Taar / Ghar / Sutra case-study data (typed block model)
public/
work/relay/ # Relay case study: cover, diagrams/, screens/
case-studies/ # 6 Liquid Glass case study PDFs
og.png # + og/ — one 1200x630 share card per route (scripts/gen-og-images.py)
resume.pdf # the resume, hosted on-site (was a Google Drive link)CHANGELOG.md · 315 lines · 55.8 KB · source ↗
27 versions since day one · latest 1.6.1, 2026-11-13
ACROSS THE BUILDS · 10 DOCS RENDERED WHOLE · SCANNED November 13, 2026
The reading room is no longer just this site's docs — every build's README and design-system front page renders whole below, pulled from its repo at index time and capped at 64 KB, with the uncapped original one click away.
README.md · 67 lines · 2.8 KB · source ↗
A modern, full-stack retail ERP built with Next.js 16, TypeScript, Prisma ORM, and Supabase PostgreSQL. Features a companion e-commerce storefront with a separate database.
Two native Android companions (Expo SDK 58 / RN 0.88.1) under `react-native/`:
react-native/shop-app (com.shubhamsupershopee.shop) — the customer storefront in your pocket: browse, search, Deal of the Day, cart, coupons, COD/UPI checkout, order history, and one-click English ↔ मराठी.react-native/erp-app (com.shubhamsupershopee.erp) — the admin ERP: passkey login, dashboard, POS, products/stock, udhar (credit) ledger, customers, reports.# Install dependencies
bun install
# Set up environment
cp .env.example .env
# Edit .env with your Supabase connection string
# Push database schema
npx prisma db push
npx prisma generate
# Start dev server
bun run dev
# Load demo data
curl -X POST http://localhost:3000/api/seedSee DEPLOYMENT.md for full Vercel + Supabase setup instructions.
<sub>Designed & developed by Omkar Kardile</sub>
README.md · 196 lines · 10.0 KB · source ↗
The owner's own cafe OS, exactly as designed: one route, fourteen screens, a platform console, and guest QR surfaces — React 19 + TypeScript + Vite + Tailwind 4 + Zustand + Supabase, installable as a PWA.
     
Since the v5 production rebuild (ADR-0014), the app equals the owner's ServePoint Figma — zero demo data, zero dev tools, a single ServePoint theme, and a typed Supabase-only data layer. Three roles (ADR-0013): SuperAdmin (provisions businesses + owners via the wizard, sees the platform console only), Owner (the full cafe app), Staff (the same app, merged Manager+Cashier). Login is email + password only — no signup, no magic links (ADR-0016 freezes the login screen).
The fourteen staff screens, named exactly what the sidebar says:
| Rail label | Section id | What it does |
|---|---|---|
| Dashboard | dashboard | The day at a glance — collections, giveaways, unpaid bills, arrivals |
| Food & Drinks | food | Ordering → GST checkout → Bills |
| Kitchen | kitchen | Live kitchen queue |
| Bills | bills | Payment collection |
| Close-out | eod | End-of-day Z-report |
| Reports | reports | Sales telemetry |
| Inventory | inventory | Stock ledger & recipes |
| Guests | customers | Loyalty & CRM |
| Floor | floor | Live tables & the booking book |
| Menu | menu | Catalog management |
| Settings | settings | Workspace preferences |
| Messages | messages | Staff chat |
| Notifications | notifications | The bell feed |
| Support | support | Help desk |
A superadmin account instead gets the Platform console — provisioning businesses + owners, platform analytics, and the guest QR surfaces serve the cafe's diners (below).
src/App.tsx)The user-visible SPA lives on one route, /. Sections are app state, not routes — in-app navigation keeps the URL where it is; the paths below are read once on mount as doors into the app.
| Path | Who | What happens |
|---|---|---|
/ | anyone | Auth gate → signed-out sees the frozen login; owner/staff land in the cafe app; superadmin lands in the platform console — always. |
/:screen · /:slug/:screen | staff | Deep links (v5.32.0): boots straight into the named screen — bookmarks, staff shortcuts, pinned wall displays. The slug segment is decorative; the signed-in session decides the workspace. |
/close-out, /guests | staff | Spoken-name aliases (v5.93.0): the rail's words resolve — /close-out → Close-out (eod), /guests → Guests (customers). Plain ids (/eod, /customers) keep working untouched. |
| unknown path | anyone | Honest 404 (v5.141.0): every address that is not the staff root, a porch page, a guest surface, or a known staff slug lands on the 404 register — nothing is silently swallowed into login. |
/showcase | public | Product showcase porch (no auth, first-paint marketing). |
/help, /index-help | public | Help porch. |
/t/:qr_token | guest | Table gate (v5.3.0): the physical table's permanent QR token is the capability — resolves the table, opens the menu. |
/menu/:qr_token | guest | Menu + cart: ordering with GST checkout; persists across reload. |
/track/:orderId | guest | Order tracking: the order UUID is the pager — live status without login. |
Guest surfaces are public and capability-addressed: no session, the token in the URL is the permission (table QR flow per ADR-0005 — ephemeral 10-minute HMAC-SHA256 table sessions). Full spec: `docs/TABLE_SIDE_ORDERING_AND_QR_CLIENT_SPEC.md`.
Deep links resolve through SECTION_SLUGS in src/App.tsx, which is derived from SECTION_LABELS in src/components/shell/Sidebar.tsx — the sidebar's words are the URLs. Two rail names differ from their section ids (the rail says "Close-out", the code says eod; the rail says "Guests", the code says customers), so both words resolve.
#F6F5F2, sage surfaces #D9E2DD,deep-teal primary #0F3D3E, gold accent #B88E2F, Poppins type, radii 12/16/24/100 — EXACT tokens per ADR-0012 (Figma REST pipeline; all 57 Final UI screens archived at docs/design/servepoint/).
servepoint → tessera → dark.ADR-0010/0016, plus porch and guest surfaces) stay force-pinned Tessera.
Frontend: React 19 + TypeScript 7.0 + Vite 8.3 + Tailwind CSS 4.3 + Lucide Icons
State engine: Zustand (persistent local store + optimistic updates)
Backend & DB: Supabase (PostgreSQL 15+, PL/pgSQL RPCs, Row-Level Security)
PWA: Service worker with versioned precache (public/sw.js); offline banner + install card
Screens: Lazy-loaded per section (v5.143.0) — a failed chunk import degrades into
that screen's recovery card while the shell stays upthe content card, never the shell.
while the app is open; platform accounts skip it.
supabase/migrations/ — numbered, additive-only(no drops, no renames, no NOT NULL without default), applied via the scripts/apply-*.mjs pooler pattern.
servepoint/
├── src/
│ ├── App.tsx # Route grammar + role gates (the file this README narrates)
│ ├── components/
│ │ ├── auth/ # Frozen login screen (ADR-0016)
│ │ ├── shell/ # AppShell, Sidebar, PwaLayer, boundaries, skeleton
│ │ ├── dashboard/ food/ kitchen/ bills/ eod/ reports/
│ │ ├── inventory/ customers/ floor/ menu/ settings/
│ │ ├── messages/ notifications/ support/
│ │ ├── platform/ # SuperAdmin console
│ │ ├── guest/ # Guest QR surfaces (gate / menu / track)
│ │ ├── pages/ # Porch + 404 register (eager on purpose)
│ │ └── common/ # Shared primitives
│ ├── lib/ # Typed data layer & pure derivations
│ │ ├── api.ts supabase.ts authService.ts tenant.ts rbac.ts
│ │ ├── billing.ts csv.ts printFrame.ts prefs.ts
│ │ └── appday.ts bookingday.ts day.ts turn.ts # Day/verdict grammar (IST, one clock per surface)
│ ├── store/ # Zustand root store (session, UI)
│ └── types.ts
├── public/sw.js # Service worker — VERSION bumped per release
├── supabase/migrations/ # Numbered, additive-only SQL (001 → 038)
├── scripts/ # apply-*.mjs appliers, unit suites, QA probes
├── docs/
│ ├── decisions/ # ADRs 0001 → 0016
│ ├── design/servepoint/ # The owner's Figma, archived (57 screens)
│ ├── compacts/ requests/ research/ worklog/
│ ├── CREDENTIALS.md # All logins (not for production use)
│ └── *_SPEC.md # Surface specs (QR, loyalty, printers, inventory…)
├── CHANGELOG.md # Release ledger (v5 line)
├── render.yaml vercel.json # Deployment blueprints
└── vite.config.tsgit clone https://github.com/OmKardile/servepoint.git
cd servepoint
npm install # or: bun install
npm run dev # or: bun run dev — serves on http://localhost:3000Gates: npm run lint (TypeScript, --noEmit) must be green before every commit. There is no unit test framework — verification is browser QA against the dev server plus the pure-derivation probe scripts in scripts/.
servepoint-tsos, zero sleep delay): deploy viaRender Blueprints using `render.yaml` — the blueprint pins the service name, SPA rewrite /* -> /index.html, immutable asset caching, security headers, Node 22, and the public anon env vars (RLS-protected). Static Site, not Web Service — the app is a pure client-side SPA with Supabase as backend; static sites never sleep.
npx vercel or GitHub import usingdocs/CREDENTIALS.md for logins.
(multi-tenant core, RLS model, ephemeral QR sessions, theme tokens, role model, the v5 rebuild, login freeze).
architecture & schema.
tiers, unit economics.
watch items, deferred census).
design-system/README.md · 62 lines · 2.8 KB · source ↗
The formal design language of ServePoint — smartPOS, extracted from the production web app by evidence (code censuses), organized for reuse. v1.0.0 · 2026-10-03 · light theme (the app's declared design)
The owner's directive: "I liked the whole site's UI/UX very much — create one whole design system around the web app. First research how to create a design system, then create it in a separate root directory." This folder is that system: research first, then an evidence-based audit, then tokens, foundations, component specs, patterns, governance, and a living showcase that renders it all.
design-system/
├── README.md ← you are here
├── CHANGELOG.md ← DS version history (semver)
├── docs/
│ ├── 01-research.md ← how design systems are created (methodology + sources)
│ ├── 02-audit.md ← the app's real design language, with census counts
│ ├── 03-foundations.md ← color, type, space, radius, elevation, motion, icons, voice
│ ├── 04-components.md ← button/card/chip/input/modal/chart/print specs
│ ├── 05-patterns.md ← honesty, arm→confirm, IST math, print honesty, a11y…
│ └── 06-governance.md ← change rules, versioning, contribution checklist
├── tokens/
│ ├── servepoint.tokens.json ← source of truth (W3C DTCG-style, 3 tiers)
│ └── servepoint.css ← drop-in CSS custom properties + utilities
└── showcase/
└── index.html ← the living style guide (open it in a browser)A warm-paper canvas (#F6F5F2) under hairline-led white cards (16px radius, #E3E7E0 borders), structured by a deep-teal spine (#0F3D3E) with a brass gold accent (#B88E2F) reserved for asks and peaks; Poppins carries dense 10–15px UI data, Instrument Serif italic speaks the human titles, JetBrains Mono handles money and code; pills dominate the geometry (306 of them); motion is a 120–160ms courtesy with reduced-motion kill switches; Lucide icons inherit text color; and the whole thing is governed by honesty — empty states explain, deltas cite stored facts, broken images vanish, zero renders zero.
/* Adopt the tokens in any surface: */
@import url('../tokens/servepoint.css'); /* or copy the :root block */
.card {
background: var(--sp-surface);
border: 1px solid var(--sp-hairline); /* hairline does the work */
border-radius: var(--sp-r-2xl); /* 16px */
}
.cta { background: var(--sp-accent); } /* gold is the ask */Read the docs in order (01 → 06) when adopting; open showcase/index.html to see every token and component rendered live.
README.md · 74 lines · 5.3 KB · source ↗
E-commerce + operations platform for Patel Networks (Surat, Gujarat): CCTV, surveillance and networking hardware retail & B2B trade. Storefront brand: MegaTechzy (by Patel Networks); store-ops console: Patel Networks Operations Console.
Stack: Next.js 16 (App Router) · TypeScript · Tailwind CSS 4 · shadcn/ui · Prisma ORM · PostgreSQL (Neon — dev + prod) · bun 39 Prisma models · 52 pages (32 storefront + 20 admin) · 80 API route handlers · 2 operator roles (Owner + scoped Staff) · money always integer paise Appearance: reference-derived light theme (greige canvas, caramel CTA, whisper shadows — law in `docs/REFERENCE-BLUEPRINT.md`) · token-only dark mode (same DNA at night) via the nav toggle Deployment: https://patelnetworks-5ne3.onrender.com — Render, autoDeploy from main (free plan sleeps ~15 min; first visit wakes it in ~50 s). Runbook: `deploy/RENDER-STEPS.md`. A project by Omkar Kardile — designed & built end-to-end (branding, UX, code, data model).bun install # postinstall runs `prisma generate`
bun run db:push # apply schema to PostgreSQL (Neon via .env DATABASE_URL)
bun run db:seed # full catalog + demo users (idempotent restore point)
bun run dev # Next dev server on :3000Health check: GET /api/health → {ok:true,data:{status:"healthy",db:"up"}}
Quality gates per round: bun run lint (0) · bunx tsc --noEmit (0) · bash scripts/responsive-sweep.sh + bash scripts/responsive-sweep-admin.sh (0px horizontal overflow at 375/768/1280) · docs updated in the same round (changelog.md + every affected md — documentation never lags code).
| Who | Where | Credential |
|---|---|---|
| Superadmin | /admin/login | superadmin@patelnetworks.in / patel@admin2026 |
| Test customer | /account/login | phone +91 98765 43210, OTP code appears in dev.log ([SIMULATED SMS]) |
Bootstrap admin comes fromADMIN_EMAIL/ADMIN_PASSWORDenv on first login. Never reuse sandbox credentials in production — set them per environment.
bun run db:seed builds the catalog and six months of deterministic operating history — every one of the 38 tables has data (51 buyers, 182 orders across all statuses, payments/gateway events, shipments/tracking events, returns, reviews, carts, wishlists, B2B inquiries, audit trail, stock-monitor sessions) — see D-15 in decisions.md. bun run scripts/qa-fixtures.ts adds a few extra console demos (B2B inquiries, wishlist price-drop, pending review). Purge before go-live: bun run scripts/qa-clean.ts + a fresh db:seed.
| Doc | Purpose |
|---|---|
| `docs/README.md` | Full docs index |
| `docs/ROUTES.md` | Routes cheat sheet: every URL + login pages & credentials (staff login = /admin/login) |
| `technical-documentation.md` | Tech hub: architecture, module map, API index, conventions |
| `business-documentation.md` | Business model, ops flows, GST, vendor integrations, roles |
| `business-pitch.md` | The designer's pitch: what the platform is, why it's special, business outcomes — visual version lives at /showcase |
| `changelog.md` | Release-by-release change log |
| `docs/REFERENCE-BLUEPRINT.md` | Storefront design law: live-verified reference sequence, layout constraints, tokens, component architecture, frozen contracts |
| `decisions.md` | Decision log (conflict resolutions + ADRs, incl. recent) |
| `help.md` | Operator help: how to run the store day-to-day, troubleshooting |
| `compact.md` | One-file compact context (stack, commands, conventions, state) |
| `worklog.md` | Agent work journal (per-round, three-section handover) |
| `docs/ENVIRONMENT-VARIABLES-GUIDE.md` | Every env var explained |
| `deploy/DEPLOY-STEPS.md` | Terse VPS (Docker) deploy runbook |
| `deploy/RENDER-STEPS.md` | Render + Neon deploy runbook (Blueprint or manual) |
| `docs/VPS-SETUP-GUIDE.md` | Phased VPS setup (Docker, TLS, backups) |
| `docs/PHYSICAL-SERVER-SETUP-GUIDE.md` | Bare-metal in-shop server guide |
| `docs/RENDER-DEPLOYMENT.md` | Staging preview on Render |
| `docs/incidents/2026-09-27-render-502-proxy-unreachable.md` | Incident post-mortem: the go-live HTTP 502 (Render proxy ↔ Next standalone bind trap) |
| `docs/PRODUCTION-CHECKLIST.md` | Go-live checklist + smoke test |
Official: https://github.com/OmKardile/patel-networks.git (deploy from main).
No AI-generated imagery. Product/seed images come from real files indexed in prisma/seed-images.json (local public/images/seed/**). Typographic placeholders render when an image is missing.
README.md · 178 lines · 9.5 KB · source ↗
A multi-niche technology publication with a split publishing model: one admin account with full control and an AI drafting tool, and open signup for regular users who write and publish manually — no AI access on that side. Built on Next.js 15 (App Router) + Supabase, styled distinctly rather than with default templates. Design system v2 (restored 2026-11-11): lucide icons, Fraunces/Cormorant/Inter type, blue accent, rounded surfaces — with the /shopping console layout (status strip, stage readout, ranked ledger) retained on the original cream/coral palette.
New here? Readcompact.mdfirst (one-page catch-up), then this README. Dev reference:technical-documentation.md· decisions:decisions.md· troubleshooting:help.md· why it exists:business-documentation.md.
tech-site/
├── website/ ← the actual Next.js application — start here
├── Guides/ ← setup docs: how to run, database, AI keys, what to edit, deployment
├── marketing-page/ ← static marketing page (also served in-app at /showcase)
├── design-research/ ← editorial design research notes
├── compacts/ ← historical session-compaction summaries
├── data/ ← legacy scrape record (products are live-AI now)
├── archived/ ← frozen pre-rebuild snapshot (website-backup) — read-only history
├── prompt.md ← original 1,278-line build spec (historical)
├── README.md ← this file
├── CHANGELOG.md ← LEGACY log of the pre-rebuild project — current log: website/CHANGELOG.md
├── compact.md ← one-page catch-up summary — read first
├── technical-documentation.md / business-documentation.md
├── decisions.md ← dated decision log
└── help.md ← troubleshooting & FAQcd website
npm install
npm run devOpen http://localhost:3000 — the full public site loads immediately with real sample content across all 10 niches, no setup required.
Everything else — connecting a real database, turning on the admin's AI drafting button, going to production — is covered in Guides/, starting with Guides/00-how-to-run.md.
lib/niches.ts, slugs immutable): AI Tools, Programming, Android, Windows, Gadgets, Gaming, Career, Finance, Productivity, PC Hardware/profile/@username) — avatar, bio, links, interests, published articleslib/ai-router.ts: 3.8-flash → 3.7-flash → 3.6-flash, then Groq fallback). No offline catalog./shopping) — natural-language picks with reasoning and buy links/pc-builder) — budget + use-case builds with component reasoning/compare) — side-by-side specs, per-row winners, verdictwebsite/supabase/schema.sql)lib/ai-router.ts/privacywebsite/
├── app/
│ ├── (main)/ ← public site chrome (Header, Footer)
│ │ ├── page.tsx ← homepage (personalized when logged in)
│ │ ├── articles/[slug]/
│ │ ├── profile/[username]/
│ │ ├── profile/@me/ ← redirect to own profile
│ │ ├── library/ ← personal knowledge space
│ │ ├── dashboard/ ← user's own posts
│ │ ├── write/ ← article editor
│ │ ├── guides/ ← buying guides
│ │ ├── products/[slug]/
│ │ ├── compare/ ← product comparison
│ │ ├── shopping/ ← AI shopping assistant
│ │ ├── pc-builder/ ← AI PC builder
│ │ ├── onboarding/ ← 3-step new user flow
│ │ └── admin/ ← admin panel (separate auth)
│ ├── (auth)/ ← auth pages (no site chrome)
│ └── api/ ← admin endpoints, search index
├── components/
│ ├── ui/ ← Button, Input, Field primitives
│ ├── admin/ ← AdminNav, PostForm
│ └── ... ← feature components
├── lib/
│ ├── data.ts ← public post queries
│ ├── library.ts ← bookmarks, history, collections, highlights, notes, follows
│ ├── products.ts ← product catalog, recommendations, buying guides
│ ├── supabase/ ← client/server/admin clients
│ ├── auth.ts ← admin JWT session
│ ├── ai-router.ts ← central AI router (Gemini chain → Groq fallback)
│ ├── live-products.ts ← live AI product data
│ ├── ai.ts ← admin AI drafts
│ ├── niches.ts ← 10-niche taxonomy + colors
│ └── utils.ts ← slugify, dates, reading time, cn()
├── content/
│ ├── articles/ ← 11 seed articles (markdown)
│ └── seed-posts.ts ← local demo data
├── scripts/hash-password.mjs, gen-version.mjs
├── supabase/schema.sql ← DB schema source of truth (20 tables)
├── middleware.ts ← Supabase session refresh
└── globals.css ← theme variables, prose-tech, code blockscd website
npm run dev # dev server (port 3000)
npm run build # production build
npm run start # run production build
npm run lint # ESLintRequired in website/.env.local (full reference: website/.env.example + website/docs/environment.md):
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
ADMIN_SESSION_SECRET=... # random 32+ char string
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD_HASH_B64=... # bcrypt hash, base64-encoded (run: npm run hash-password)
GEMINI_API_KEY=... # products / shopping / pc-builder / admin drafts
GROQ_API_KEY=... # optional: fallback AI pool (separate quota)
RESEND_API_KEY=... # optional: contact form email
NEXT_PUBLIC_SITE_URL=... # canonical URL (metadata, sitemap)website/supabase/schema.sql in SQL Editor (idempotent, safe to re-run — 20 tables, the current source of truth)localhost:3000 and production URL to Supabase Auth → URL Configuration → Redirect URLs.env.local with project credentialsSee Guides/01-database-setup.md for full walkthrough.
website/supabase/schema.sql — idempotent, re-runnableGuides/sql/ (v4.0-era schema, seeds, scraped-catalog SQL — historical; review before applying anything to the current project)website/CHANGELOG.mdSee website/CHANGELOG.md (current, 1.x series) for version history. Root CHANGELOG.md is the legacy pre-rebuild log, preserved as history.
README.md · 170 lines · 10.3 KB · source ↗
One card. One scan. Nothing leaves your phone.
Vello is a privacy-first digital business card web app. It generates a compact vCard QR code from your contact details, lets you style it beautifully (Instagram/Telegram-style), and export or share it — all 100% local. No server. No network. No accounts. No tracking.
Built with Next.js 16, TypeScript, Tailwind CSS 4, shadcn/ui, Zustand, IndexedDB (idb-keyval), qr-code-styling, jsQR, libphonenumber-js and next-themes. MIT licensed.
check:privacy script enforces this: app code in src/ must not contain fetch(), XMLHttpRequest, WebSocket, EventSource, or sendBeacon.bun install
bun run devOpen http://localhost:3000. The dev server also tees its output to dev.log (see package.json → scripts.dev).
Build for production:
bun run build
bun run start # serves the standalone server from .next/standalone| Script | What it does |
|---|---|
dev | next dev -p 3000, output also written to dev.log |
build | next build then copies .next/static and public/ into .next/standalone/ |
start | Runs the standalone production server (bun .next/standalone/server.js) and tees to server.log |
lint | eslint . across the whole repo |
docs:check | Validates every required doc exists, is non-empty, all relative markdown links resolve, and every script in package.json is mentioned somewhere in docs |
check:privacy | Greps src/ and scripts/ for network-call patterns (fetch, XMLHttpRequest, WebSocket, sendBeacon, EventSource) and absolute URLs not on the allow-list |
verify:all | Runs lint → docs:check → check:privacy in sequence |
db:push | prisma db push --accept-data-loss |
db:generate | prisma generate |
db:migrate | prisma migrate dev |
db:reset | prisma migrate reset |
The db:* scripts are scaffolding for a Prisma schema that the runtime app does not use. Vello stores data in IndexedDB only; Prisma is unused at runtime and included for compatibility with the surrounding workspace. See docs/ARCHITECTURE.md. ┌─────────────────────────────────────────────┐
│ src/shared/ │ brand.ts, types.ts, limits.ts
│ (types, brand, limits — no dependencies) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ src/lib/ │ normalizers, vcard, qr, qr-render,
│ (pure logic — no React, no DOM) │ scan-check, photo, export, storage,
│ │ style-presets, store (zustand), haptics
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ src/components/ │ view-context, app-shell, qr-preview,
│ (React: screens, app shell, UI) │ screens/{onboarding,home,editor,...}
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ src/app/ │ layout.tsx (fonts + theme + sonner),
│ (Next.js App Router shell) │ page.tsx (loads store → AppShell),
│ │ globals.css (design tokens)
└─────────────────────────────────────────────┘Data flow at runtime:
Card (typed) → buildCompactVcard → QR payload → qr-code-styling → canvas → PNG/SVG/story/print/wallet/.vcf export
↓
qrFingerprint (SHA-256, first 8 bytes hex) → "QR changed" banner detectionStorage adapter (IndexedDB via idb-keyval):
vello-db / vello-store → vello:card, vello:card.bak, vello:style, vello:settings,
vello:photo, vello:presets, vello:onboardedSee docs/ARCHITECTURE.md for the full layered walk-through and Mermaid diagram.
The original product spec targeted Vite + React + Capacitor for native iOS/Android. This build adapts Vello to a Next.js 16 App Router environment, which is what the surrounding workspace provides. Concretely:
/). The product's planned /showcase and /index-help routes are therefore implemented as client-side SPA views inside the existing view router (src/components/vello/view-context.tsx), reachable from Settings → Showcase and Settings → Help centre. They are not separate Next.js routes — they are React components switched on a single route.This is honestly reflected in docs/KNOWN_ISSUES.md and docs/RELEASE.md.
The privacy guarantee is enforced by the check:privacy script (scripts/check-privacy.ts). It walks every .ts/.tsx/.js/.jsx file under src/ and scripts/, fails on any of:
fetch(, XMLHttpRequest, new WebSocket, navigator.sendBeacon, new EventSourcehttp(s):// URLs that are not on the allow-list (canonical social-URL builders, the author link, localhost, example.com)Files exempt from the URL check: scripts/check-privacy.ts (it's the checker) and src/lib/qr-render.ts (only has crossOrigin comments). Run it with bun run check:privacy, or run everything at once with bun run verify:all.
There is no automated test suite yet. Verification is manual via agent-browser (iPhone 14 emulation), covering the full onboarding → home → studio → share → export flow plus theme switching and the fullscreen QR view. See docs/TESTING.md for the test strategy and the known gap.
Vello is a Next.js 16 app. Production runs as a standalone Node server (bun .next/standalone/server.js, see the start script). It can also be deployed as a normal Next.js app on Vercel, Netlify, or any Node host that can run .next/standalone.
For a fully static export, additional Next.js configuration would be required (output: 'export') and is not currently enabled — see docs/KNOWN_ISSUES.md.
index.html yet — the app makes zero runtime network requests regardless, but a default-src 'self' policy is recommended before public launch (see docs/BACKLOG.md).appId (com.example.vello) is a placeholder and must be changed before any store submission. See docs/STORE.md.Full documentation lives in `docs/`. The index is at docs/README.md.
| File | What it covers |
|---|---|
| CHANGELOG.md | Release history |
| CONTRIBUTING.md | Setup, conventions, how to extend |
| LICENSE | MIT License |
| THIRD_PARTY_LICENSES.md | Dependency licences |
| docs/README.md | Documentation index |
| docs/DECISIONS.md | Decision log |
| docs/ARCHITECTURE.md | Layers, data flow, storage, build |
| docs/TECHNICAL.md | Module-by-module reference |
| docs/DATA_MODEL.md | Card, QrStyle, Settings, PhotoData, presets |
| docs/TESTING.md | Test strategy and known gaps |
| docs/SECURITY.md | Threat model for a local-only app |
| docs/PRIVACY.md | Plain-language privacy policy |
| docs/RELEASE.md | Version bump, build, submission |
| docs/DESIGN.md | Design rationale, tokens, screen inventory |
| docs/BRAND.md | Name, tagline, identifiers, voice |
| docs/FIGMA_GUIDE.md | Designer import package |
| docs/STORE.md | Store listing, data safety, privacy |
| docs/AUTOMATION.md | Scheduled review cron, scripts |
| docs/BACKLOG.md | Prioritised improvements |
| docs/KNOWN_ISSUES.md | Honest list of known limits |
| docs/PROGRESS.md | Current status |
| docs/BUSINESS.md | Positioning, market, monetisation |
| docs/USER_GUIDE.md | End-user manual (mirrors in-app help) |
| docs/FAQ.md | Frequently asked questions |
| docs/TROUBLESHOOTING.md | Common issues and fixes |
MIT — see LICENSE.
Designed & developed by Omkar Kardile.
design-system/README.md · 80 lines · 2.6 KB · source ↗
The single source of truth for HandOff's visual language and interaction patterns. Encoding the brutalist "DEAD DROP" aesthetic so any contributor can build on-brand screens.
This directory documents and codifies the HandOff design system — the palette, typography, spacing, components, and patterns that make the app look and feel like HandOff.
It is separate from the app source (src/) so it can be consumed by:
design-system/
├── README.md ← you are here (start here)
├── tokens/ ← raw values (color, type, spacing, radius, motion, elevation)
│ ├── color.md
│ ├── typography.md
│ ├── spacing.md
│ ├── radius.md
│ ├── motion.md
│ └── elevation.md
├── primitives/ ← building blocks (atoms)
│ ├── surfaces.md (.brut, .brut-lg, .brut-sm, .brut-signal, .brut-ink)
│ ├── borders.md
│ ├── field-label.md
│ └── textures.md (field-grid, scanlines, grain, tape)
├── components/ ← composed UI (molecules)
│ ├── button.md
│ ├── input.md
│ ├── card.md
│ ├── nav-bar.md
│ ├── screen-header.md
│ ├── scan-badge.md
│ └── qr-preview.md
├── patterns/ ← screen-level conventions
│ ├── layout.md
│ ├── titles.md
│ ├── color-on-lime.md
│ └── gestures.md
└── DESIGN-PRINCIPLES.md ← the philosophy / guardrails| Token | Value |
|---|---|
| Bone (canvas) | #F2EFE6 |
| Ink (text/border) | #0A0A0A |
| Signal (lime accent) | #C6FF00 |
| Clay (vermilion alert) | #FF3B1F |
| Cobalt (data accent) | #1B2BE0 |
| Display font | Anton (heavy condensed uppercase) |
| Body font | Space Grotesk |
| Mono font | JetBrains Mono |
| Card radius | 28px (--radius-xl) |
| QR plate radius | 28px (matches card) |
| Border | 2px solid ink |
| Card shadow | 4px 4px 0 0 ink (hard, no blur) |
| Primary action | bg-signal text-black + hard shadow |
Black text on yellow. Always.--inkflips to bone in dark mode. So on any lime/yellow surface, NEVER usetext-inkorvar(--ink)— use the fixedtext-black(#000). This is the most common bug.
See DESIGN-PRINCIPLES.md for the full philosophy, then dive into tokens/.
README.md · 43 lines · 2.0 KB · source ↗
A lightweight android network monitor focused on a persistent live-speed notification, daily Wi-Fi/mobile usage history, and per-app traffic breakdowns.
NetworkStatsManagerPACKAGE_USAGE_STATS is required for accurate daily and per-app usage trackingREAD_PHONE_STATE improves signal-strength reportingPOST_NOTIFICATIONS keeps the foreground monitor visible on Android 13+When you first open the app, grant usage access from system settings so the history/calendar screen can populate correctly.
The project includes a Gradle wrapper and points at the local Android SDK in local.properties.
If command-line builds fail on this machine, increase the Windows paging file or build through Android Studio, because the local environment is currently failing to start the Gradle JVM reliably.
Prerequisites: Android Studio
.env in the project directory and set GEMINI_API_KEY in that file to your Gemini API key (see .env.example for an example)build.gradle.kts file: signingConfig = signingConfigs.getByName("debugConfig")README.md · 314 lines · 33.4 KB · source ↗
A premium, weather-reactive PWA weather app with a macOS "Liquid Glass" design system and a grounded AI layer. Live conditions, a 48-hour outlook, 7-day forecast and air quality — rendered inside a macOS-style window shell over a full-viewport sky that changes with the weather and the time of day.
!Next.js !React !TypeScript !Tailwind CSS !PWA !Weather data !AI !License
Aether is a ground-up rebuild of OmKardile/weather-nextjs: rebranded, rewritten in strict TypeScript on Next.js 16 + React 19, and freed from hardcoded API keys by moving all weather data to the keyless Open-Meteo API behind server-side route handlers. v2 adds the macOS Tahoe Liquid Glass design language, a macOS window layout with a ⌘K Spotlight palette, a unified animated icon system, and four server-side AI features (briefing, chat, advisor, alert digest) that degrade gracefully all the way down to deterministic rule-based text.
Liquid Glass design system (macOS Tahoe) — a two-layer iOS 27 material system — <LiquidGlass> controls (runtime 3-pass RGB refraction, opposing-corner rim light, press gel, ≤3 lens filters) over flat <Glass>/Surface content cards, with a hero composed directly on the sky. Every surface adapts to the live weather via [data-tint]/[data-surface], and a Settings transparency slider (Ultra Clear → Fully Tinted) drives tint, blur, refraction and rim brightness. On devices with a motion sensor, an opt-in Tilt highlights setting makes the specular light drift with the physical tilt of the device (permission-gated on iOS).
macOS window layout
lg; it carries only real controls there (°C/°F, ambient volume at sm+, search), while desktop keeps every control in the top bar. The Today tab carries an alert badge (v4.3.0) — a severity-tinted count pill that appears while you're on another tab, taps give a subtle haptic tick, and the whole app installs from Settings (PWA install prompt / iOS Add-to-Home-Screen hint)AI, grounded in your forecast (server-side only, details below)
Weather-reactive scene engine — 32 hand-tuned scenes (8 conditions × 4 day phases: day / dawn / dusk / night). Canvas-rendered rain and snow particles, twinkling stars with a shooting star, moon and sun with golden-hour halos, drifting aurora curtains, parallax clouds, fog banks and lightning — all crossfading over 600 ms whenever the sky changes.
Weather data (Open-Meteo)
/ shortcut)UX niceties
localStorage, plus last-visited-city restorePWA — installable, with an offline shell service worker (precached shell, network-first navigations, cache-first statics; API calls always live).
Accessibility — full keyboard support (search combobox, chart scrubbing, command palette, everything reachable), ARIA live announcements for weather and status changes, screen-reader labels on all controls, and prefers-reduced-motion support across every animation (including icons and the specular light).
| Layer | Choice |
|---|---|
| Framework | Next.js 16 (App Router, Turbopack, route handlers) |
| UI | React 19, Tailwind CSS 4 (CSS-first @theme tokens), shadcn/ui-style primitives, lucide-react |
| Glass / motion | <Glass> primitive + use-specular hook; framer-motion springs (lib/motion.ts) |
| Icons | Bespoke <Icon name size animated strokeWidth /> system — no icon-font, no emoji |
| Palette / drawer | cmdk (⌘K command palette), vaul (snap-point drawer) |
| AI | @google/genai (Gemini) → z-ai-web-dev-sdk → deterministic fallback; zod-validated payloads & structured outputs; react-markdown (markdown-lite rendering) |
| Data fetching | TanStack Query (60 s stale time, 1 retry, keeps last good data on refetch failure) |
| State | zustand with persist middleware (units, theme, saved cities, last city) |
| Charts | Hand-rolled SVG — a few kB instead of a chart library |
| Language | TypeScript, strict mode, zero any in app code |
| Fonts | Sora (display) + Inter (text) via next/font |
Architecture highlights:
/api/weather and /api/geocode route handlers call Open-Meteo server-side with a 10-minute shared cache. No API keys, no client-visible upstream URLs, and Nominatim's User-Agent requirement is handled where it belongs (the server).src/lib/ai.ts is server-only.src/lib/scenes.ts maps WMO weather codes × day phase to a SceneConfig; the scene engine is a pure consumer of that config, and the same config drives data-surface (light/dark tokens) and data-tint (glass hue).WeatherIcon (v1 API) is now a thin compatibility wrapper over the unified <Icon /> system, so the hero, hourly strip and daily rows all share one implementation.npm install # or: bun install / pnpm install
npm run dev # start the dev server on http://localhost:3000
npm run build # production build
npm start # serve the production build
npm run lint # eslint
npm run icons # regenerate PWA PNGs (public/icons, src/app/apple-icon.png) from the brand SVG via sharpOptional — enable Gemini AI (the app works fine without it):
cp .env.example .env # then set GEMINI_API_KEY=... (https://aistudio.google.com/apikey)├── public/
│ ├── icons/ # PWA PNG icons (192 / 512 / maskable-512)
│ ├── logo.svg # brand mark
│ ├── robots.txt
│ └── sw.js # offline-shell service worker
├── scripts/
│ └── generate-icons.mjs # sharp-based PWA icon generator (npm run icons)
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ ├── ai/ # POST briefing / chat / advisor / alerts (streamed NDJSON)
│ │ │ ├── geocode/route.ts # GET ?q=<query> (search) | ?lat=&lon= (reverse)
│ │ │ └── weather/route.ts # GET ?lat=&lon= — Open-Meteo proxy (forecast + air quality)
│ │ ├── globals.css # Tailwind 4 @theme tokens, [data-tint] glass tints,
│ │ │ # scene-aware shadcn vars, motion keyframes
│ │ ├── layout.tsx # Sora + Inter fonts, metadata, providers, toaster
│ │ ├── manifest.ts # PWA web app manifest
│ │ ├── icon.svg # favicon (source for PNG icons)
│ │ ├── apple-icon.png # iOS touch icon
│ │ ├── opengraph-image.tsx # dynamic OG image (next/og)
│ │ ├── instrumentation.ts # IPv4-first DNS / Happy-Eyeballs at server boot
│ │ └── page.tsx # renders <AetherApp />
│ ├── components/
│ │ ├── ai/ # BriefingCard, AskAIPanel, AdvisorCards, AlertDigest,
│ │ │ # ai-shared (NDJSON reader, badge, markdown-lite)
│ │ ├── brand/Logo.tsx # logo mark + AETHER wordmark
│ │ ├── glass/ # <Glass> primitive + glass.css (Liquid Glass levels)
│ │ ├── icons/ # <Icon /> system + icons.css (weather + UI glyph sets)
│ │ ├── layout/ # MenuBar, CitiesSidebar, CommandPalette, MobileDock,
│ │ │ # ForecastDrawer, SettingsSheet (macOS window shell)
│ │ ├── providers.tsx # TanStack Query provider + SW registration (production only)
│ │ ├── ui/ # shadcn-style primitives actually used
│ │ │ # (command, dialog, toast, toaster)
│ │ └── weather/ # the app: AetherApp orchestrator, hero, ForecastSections,
│ │ │ # hourly, chart, daily, metrics, air quality, moon phase,
│ │ │ # saved cities, state views, footer, WeatherIcon wrapper
│ │ └── scene/ # canvas rain/snow + CSS layer scene engine
│ ├── hooks/ # use-weather, use-city-search, use-geolocation, use-ai-chat,
│ │ # use-specular, use-preferences (zustand persist),
│ │ # use-toast
│ ├── lib/ # ai (provider chain + guardrails), ai-fallback (deterministic),
│ │ # openmeteo (server client), wmo (code→condition),
│ │ # units (converters/formatters), aqi, time (location-local),
│ │ # moon (phase math), motion (framer-motion presets),
│ │ # scenes (32 configs), cities, utils
│ └── types/ # weather.ts + ai.ts shared data contracts
├── components.json
├── eslint.config.mjs
├── next.config.ts
├── package.json
├── postcss.config.mjs
└── tsconfig.jsonNo environment variables are required. All weather data is keyless, and every AI feature falls back to deterministic rule-based text when no key is configured.
Optional — see .env.example:
| Variable | Purpose |
|---|---|
GEMINI_API_KEY | Google Gemini API key (get one free). Server-side only — never bundled, never logged. Without it the AI layer uses its fallback chain and the app still works. |
GEMINI_MODEL | Gemini model id. Defaults to gemini-3.8-flash (the current fast flash model). Override to pin or preview another model. |
NEXT_PUBLIC_SITE_URL | Absolute base URL for Open Graph / canonical metadata (e.g. https://aether.example.com). Falls back to http://localhost:3000. |
The material system is a faithful two-layer implementation of Apple's Liquid Glass:
Layer 1 — CONTROL (<LiquidGlass>). True lensing glass for controls only: the top-bar cluster, unit toggle, dock, segmented controls, sheet grabber, map controls and floating buttons. Four stacked layers per element:
backdrop-filter: url(#refraction-filter) blur(2px) saturate(1.7) brightness(1.05); everyone else: blur(18px+) saturate(1.8) (clean fallback, zero layout shift).src/lib/liquid.ts): a displacement map rasterized on a canvas from a rounded-rect signed-distance field (squircle profile ≈ Snell's law, IOR ~1.5, 12–20px bezel, zero displacement at center so content stays crisp), fed through three feDisplacementMap passes isolated per RGB channel (relative scales 1.00 / 1.05 / 1.10 on a 12.5px base) recombined with feBlend screen — the faint chromatic fringe at the rim. Filter region extends −20 %/+140 %. Cached by (w, h, radius, strength) — the slider bakes a fresh filter — regenerated on resize, and budgeted to ≤ 3 live filters (dock, top-bar cluster, one more).rgba(255,255,255,.05–.10); light scenes lift toward .34 with ink-family labels (iOS light glass uses dark labels — white glyphs over the milk fill measured ≈1.1:1 and were effectively invisible, the other root cause of the v4.1 contrast reports).inset 0 1px 0 rgba(255,255,255,.5) top highlight, inner hairline, soft inner glow; a pointer-following specular blob (rAF-throttled, desktop only, off under reduced motion) that on motion-sensor devices doubles as the tilt light — with Tilt highlights enabled the ambient specular drifts with the device's physical tilt (pointer input always wins when present); layered shadow 0 10px 30px / 0 2px 6px that intensifies while content scrolls beneath (.lg-boosted).Interaction — press = scale .96 + brighten (gel flex), release springs back with a small overshoot. Selected segments (unit toggle, dock tabs, segmented controls) are an inner lighter glass capsule that morphs between positions with a framer-motion layoutId spring and a brief scaleX stretch mid-travel.
Variants — regular everywhere; clear only for controls floating over the full-screen map (with a built-in dimming scrim). Never mixed in one view.
Layer 2 — CONTENT (Surface). All cards are deliberately flat: blur(22px) saturate(1.4), 1px hairline (.16 white on dark / .16 ink on light — a faint edge was half the “weightless panel” look), inset top highlight, soft shadow — no refraction, no specular, so controls pop above it. On dark scenes the tint is dark-teal translucent (.20 → .78 with the slider, plus a 5 % white whisper) — iOS dark materials darken the scene; a white tint here is exactly the old “milky grey slab” look. Light scenes keep the milky-white material ([data-surface='light'], strengthened a step). Chips and scrolling-list rows (.glass-subtle / .surface-subtle) are plain fills with no backdrop-filter; hero quick-stat chips use the flat .surface-chip; segmented controls inside cards render as a flat inset well (.segment-well, white-family text on dark / ink on light) with the morphing selected capsule on top; cards inside a sheet/modal (.surface-overlay …) never re-blur — the sheet already frosted the scene. Never glass-on-glass; never more than 2 stacked translucent layers.
The transparency slider (Settings → Liquid Glass, Balanced at 35 by default — Ultra Clear is a deliberate choice, since at 0 card text over bright golden-hour bottoms cannot hold AA) spans Ultra Clear → Fully Tinted and drives everything: tint alpha .04 → .55, blur 2px → 28px, refraction strength 1.0 → 0.25, rim brightness 1.0 → 0.35, plus the Surface card tint (.20 → .78 dark). It honors prefers-reduced-transparency (forces fully tinted, no refraction), prefers-contrast: more (stronger rim + tint), prefers-reduced-motion (no specular / gel), and a Reduce bright effects toggle (kills specular + chromatic fringe).
Tilt highlights (use-tilt-glow.ts, off by default) — the mobile counterpart of the pointer specular: deviceorientation → normalized --tilt-x/y custom properties on <html> (rAF-throttled CSS repaints), consumed by the specular layer as its position fallback. iOS 13+ permission is requested from the Settings switch (a denial shows a recovery hint); reduced-motion and Reduce bright effects both disable it. On fine-pointer devices the pointer light always takes precedence.
Hero — no panel at all: city, a giant thin temperature (clamp(104px, 24vw, 176px), weight 200, tracking −0.045em), condition and H/L render directly on the animated scene, with the glowing weather glyph (~200px) beside them and quick stats as a row of flat Surface chips. Hero actions (share / save / refresh) are ghost controls (.hero-ghost) — no chrome until you scroll, Apple Weather style. Scene-aware text polarity (v4.1): dark skies (dawn/dusk/night/thunder) get white vibrancy tiers (1.0 / .86 / .70) with deep text-shadows; light day skies get ink text with a soft light halo — the same treatment as the welcome heading — because no affordable dark veil can save white text over an L≈0.7 mint (measured 1.3:1, the core of the "ui destroyed" report). The scene-level hero-scrim/dock-scrim gradients render after the scene slots in DOM order (a v4.1 bug fix — the scrims were painted under the gradient and had been dead code since their introduction). The mobile forecast drawer's peek detent (0.34) is tall enough that the first card's title always clears the floating dock — cards only pass under the dock while scrolling. The dock capsule floats max(12px, env(safe-area-inset-bottom)) above the screen edge (a malformed mb-ax(...) utility had silently dropped that margin — also fixed).
Contrast contract (v4.1, tiers lifted in v4.2) — every scene marked surface: 'dark' keeps its top and middle gradient stops at WCAG relative luminance ≤ ~0.17, so white hero/menu text holds ≥ 4.5:1 before scrims or glass tints add margin (measured: hero metadata line 2.5:1 → 5–11.5:1 across dusk/dawn/night; card interiors 4.4–7.6:1 at the default). Light-surface scenes stay light but richer (deeper, more saturated stops) so panels read with definition instead of washing into the sky. Golden-hour identity lives in the warm bottom stop plus the horizon sun glow — never in bright mid-tones under text. The day sun parks in the content column (34–58% left) so its halo never bleeds through the sidebar glass as a rendering artifact. v4.2 text tiers: the secondary labels were lifted until 10–12px text holds AA — dark scenes --surface-muted .92 / --surface-faint .82 (was .8 / .66), light scenes ink .88 / .74 with --surface-text #0a2226 — one token layer, inherited by every chip, caption and sub-label.
One metric, one home (v4.2 de-duplication) — the interface previously repeated data across cards (48h temps as both a graph and a strip, UV in two cards inside Details, moon phase in two sections, sunrise/sunset in three places, two "Updated" timestamps, city+clock in the menu bar and the hero, alerts twice on mobile). Now: the hourly card is one card with an Hours | Graph segmented toggle (HourlyForecastCard); UV belongs to the Sun Safety card, feels-like to the hero + temperature dialog, moon phases to the Sky card's 14-night calendar, sunrise/sunset to the hero chip + Sun path card (the Daylight card keeps night length, the daily delta, the year gauge and the solstice countdown only); data freshness lives in the FreshnessPill (live, relative) + the footer credit; official alerts render once (mobile: drawer only); and the menu bar's resting center is empty — the compact weather summary fades in only while scrolling, exactly when the hero has left the viewport. The Details grid reflowed to 3 columns at lg so 7 tiles + the Sun path arc fill every row with no holes.
Browser support
| Browser | Refraction | Backdrop | Notes |
|---|---|---|---|
| Chrome / Edge / Brave (Chromium) | ✅ 3-pass RGB displacement + chromatic rim | url(#filter) + blur(2px) | Full recipe |
| Safari (WebKit) | ❌ (renders nothing for backdrop-filter: url() — detection is UA-based, never CSS.supports) | blur(18px+) saturate(1.8) | Clean frosted fallback |
| Firefox | ❌ | blur(18px+) saturate(1.8) | Same fallback |
Performance rules — ≤ 6 live backdrop-filter elements on screen (browser-audited: 6 mobile / 4 desktop at rest); ≤ 3 refraction filters (slot budget with graceful blur fallback); cards inside overlays never re-blur (one blur per sheet, not per card); card sections keep content-visibility virtualization; no backdrop filter on scrolling list rows; pointer specular is rAF-throttled, hover-capable-pointer-only, and pauses offscreen. Under prefers-reduced-transparency every material falls back to a solid fill (dark teal for controls and cards, off-white on light scenes) so nothing turns see-through when the blur is gone.
Scene scenery — every scene paints large soft light blobs, a diagonal gradient band and small high-contrast orbs near the top and bottom edges (calm middle for text), so the lensing has living light to bend. Blobs drift slowly; everything is seeded-random and SSR-stable.
import { LiquidGlass } from '@/components/glass/LiquidGlass';
import { Glass } from '@/components/glass/Glass';
import { SegmentedControl } from '@/components/glass/SegmentedControl';
<LiquidGlass className="flex h-11 items-center rounded-full px-3">…</LiquidGlass> // control
<LiquidGlass as="button" onClick={…} aria-label="Save">…</LiquidGlass> // pressable control
<LiquidGlass variant="clear">…</LiquidGlass> // over the map only
<Glass level="base" className="rounded-[var(--radius-card)] p-5">…</Glass> // content card
<SegmentedControl aria-label="View" options={…} value={view} onChange={setView} />The legacy utility classes (.glass, .glass-strong, .glass-subtle, .glass-hover, .surface-*) now map onto the Surface recipes — migrated components keep working.
Text on glass — vibrancy tiers (white at 1.0 / .72 / .5) on scene and controls via .text-on-scene / -2 / -3; on cards via the --surface-* tokens. Labels are sentence-case 13px (.card-label / .card-label-muted) — no tracked-out micro caps. Dark text never sits on a dark scene; the scene scrim guarantees AA.
Icon system — import { Icon } from '@/components/icons/Icon':
<Icon name="partly-cloudy-day" size={64} animated /> // weather glyph (gradient-lit, animated)
<Icon name="sparkle" size={16} strokeWidth={2} /> // UI icon (currentColor strokes)sun, moon, partly-cloudy-day, partly-cloudy-night, cloudy, fog, drizzle, rain, thunder, snow, wind, hailsearch, pin, gear, plus, check, x, chevron-up/down/left/right, sparkle, droplet, thermometer, eye, gauge, sunrise, sunset, bookmark, send, stop, refresh, locate, command, info, alert, moon-phase, compareuseId(), so dozens of icons can share a page (hourly strip) without collisions; a shared IntersectionObserver pauses off-screen animations; prefers-reduced-motion renders everything static.Adding a scene — add a config to src/lib/scenes.ts (getScene(condition, phase) maps WMO codes × day phases to SceneConfig: gradient stops, surface mode, layer flags). The scene engine, glass tint and light/dark surface tokens all derive from it — no component changes needed. Test with ?scene=<condition>&phase=<phase> (see Debug & QA).
Adding an icon — add a glyph factory to WEATHER_GLYPHS or UI_GLYPHS in src/components/icons/Icon.tsx (and the corresponding name in the union type). Namespace any gradient/mask ids with the id argument, gate looping animations on the root .ic-anim class, and add keyframes to icons.css.
Four route handlers, all POST, server-side only, all validating their payload with zod:
| Route | What it does | Cache | Rate limit (per IP) |
|---|---|---|---|
/api/ai/briefing | 2–3 sentence daily briefing, streamed | 30 min | 20 / min |
/api/ai/chat | Grounded chat over the live forecast (8-turn history), streamed | never | 12 / min |
/api/ai/advisor | Outfit suggestion + 5 activity scores (0–100), structured JSON | 30 min | 12 / min |
/api/ai/alerts | Notable changes as severity-tagged alerts (facts detected deterministically, AI only phrases them) | 15 min | 20 / min |
Streaming routes speak a tiny NDJSON protocol: {type:"meta",provider,cached} → {type:"chunk",text}… → {type:"done"} (or {type:"error",message}).
Provider chain — every route runs the same chain in src/lib/ai.ts:
@google/genai with GEMINI_API_KEY / GEMINI_MODEL (default gemini-3.8-flash). A circuit breaker permanently disables it for the process after fatal errors (invalid key, unsupported region).src/lib/ai-fallback.ts) — rain windows, dry stretches, band-scored activities and threshold-detected alerts, computed directly from the forecast. The AI UI never hard-fails: with no provider at all you still get a useful (sparkle-free) summary, and the badge honestly says so.Guardrails
AbortSignal.any)advisor) are requested with a Gemini responseSchema and re-validated with zod; anything invalid falls back to deterministic scoringSwapping the model — set GEMINI_MODEL in .env (any current Gemini model id) and restart. That's the whole swap; the SDK, prompts and schemas stay unchanged.
Force any background scene without waiting for the weather:
http://localhost:3000/?scene=<condition>&phase=<phase>scene: clear · partly-cloudy · cloudy · fog · drizzle · rain · snow · thunderphase: day · dawn · dusk · nightA small badge in the bottom-left corner confirms the override is active. Handy for checking all 32 scene combinations (e.g. ?scene=thunder&phase=night for lightning, ?scene=snow&phase=day for snowfall) — and since the glass tint follows the scene, for QA-ing glass legibility across every condition.
/api/* (weather must be fresh).localhost).Works on Vercel as-is — zero configuration. Just import the repo; next build handles the rest. Add GEMINI_API_KEY (and optionally GEMINI_MODEL, NEXT_PUBLIC_SITE_URL) as project environment variables to light up the AI layer. Any Node host works too:
npm run build && npm startTargets modern evergreen browsers (latest Chrome, Edge, Firefox, Safari). backdrop-filter powers the glass aesthetic and degrades gracefully where unsupported; the refraction sheen is Chromium-only by design. Animations are transform/opacity-only and pause on hidden tabs and off-screen elements.
MIT — © 2026 Aether contributors. Weather data by Open-Meteo (CC-BY 4.0).
<sub>Designed & developed by Omkar Kardile</sub>
README.md · 149 lines · 7.8 KB · source ↗
A Next.js application that generates chef-quality Indian recipes from the ingredients you already have, powered by Google Gemini 2.5 Flash.
Enter what's in your kitchen → get three distinct recipes (a quick everyday dish, a classic comfort dish, and a weekend showstopper), each with structured ingredients, numbered steps, chef's tips, and honest timings.
prefers-reduced-motion.@google/generative-ai) — gemini-2.5-flashdata/) for personal recipes & meal plans; in-memory store for share links``bash git clone https://github.com/OmKardile/recipe-generator.git cd recipe-generator npm install ``
Get a free key from Google AI Studio, then:
``bash cp .env.example .env.local # edit .env.local and paste your key ``
``bash npm run dev ``
Visit http://localhost:3000.
``bash npm run lint # ESLint (flat config) npm run build # Production build npm start # Serve the production build ``
POST /api/generateRequest
{
"ingredients": ["Chicken", "Rice", "Tomato"],
"preferences": "Spicy, under 30 minutes",
"includeNutrition": true
}Response (abridged — each recipe also carries a ready-to-render recipe markdown string):
{
"recipes": [
{
"title": "15-Minute Chicken Tomato Pulao",
"dishName": "Chicken pulao",
"description": "A quick one-pot…",
"cuisine": "North Indian",
"difficulty": "Easy",
"prepMinutes": 10,
"cookMinutes": 20,
"totalTimeMinutes": 30,
"servings": 3,
"ingredients": [
{ "name": "Basmati rice", "amount": 1, "unit": "cup", "note": "rinsed" }
],
"instructions": ["Marinate the chicken…", "Toast the whole spices…"],
"tips": ["Swap chicken with paneer for a veg version."],
"nutrition": { "calories": 480, "protein": 32, "carbs": 58, "fat": 12 },
"recipe": "# 15-Minute Chicken Tomato Pulao\n\n## Ingredients\n- 1 cup Basmati rice…"
}
],
"model": "gemini-2.5-flash"
}Errors — 400 invalid input, 429 quota, 503 overloaded, 504 timeout, 500 missing key / server error. All errors return { "error": "human-readable message" }.
| Method | Route | Purpose |
|---|---|---|
GET/POST | /api/my-recipes | List / save personal recipes |
PATCH/DELETE | /api/my-recipes/[id] | Update tags / delete |
GET/POST/DELETE | /api/meal-plan | Weekly meal plan |
GET/POST | /api/tags | Tag library |
GET/POST | /api/settings | Misc settings |
GET | /api/recipe-media | Resolve a REAL photo of a dish (?dish=…&title=…) — Wikipedia → TheMealDB, cached |
POST | /api/recipes | Create a share link |
GET | /api/recipes/[id] | Fetch a shared recipe |
lib/prompts.js — the prompt-engineering system: role anchoring, XML-delimited sections, a diversity matrix, anti-hallucination ingredient rules, food-safety constraints, a strict JSON output contract, and the authenticity contract (real established dishes, canonical dishName, YouTube ids only when certain).lib/recipeUtils.js — response normalization (incl. dishName / youtubeVideoId), serving scaling (with vulgar-fraction formatting), deterministic markdown synthesis, legacy parsing, and shopping categorization.lib/video.js — YouTube integrity: server-side video verification (thumbnail CDN HEAD check, 24h cache), watch/search URL helpers, thumbnail candidates.lib/dishImage.js — the real-photo resolver: Wikipedia/Wikimedia Commons summary API (paced, non-food-article guard, allowed-width snapping) → TheMealDB search with word-overlap matching; 24h cache.lib/gemini.js — lazy model initialization (the app boots fine without an API key; only generation reports a clean error).data/*.json works locally and on single-instance hosts. On serverless (Vercel), the filesystem is read-only and share links live in per-instance memory — for production durability, swap lib/dataStore.js / lib/sharedStore.js for Vercel KV (the @vercel/kv dependency is already declared).Found a bug or want a feature? Open an issue or PR — run npm run lint && npm run build before submitting.
Add a license of your choice (e.g. MIT) before commercial use.
02 / Across GitHub
7 of 35 public source repos · 237 markdown documents · 3 design systems, downloadable · the rest are repos, not docs · indexed November 9, 2026
About the AI you'll see in these repos — AGENT_LOG, CLAUDE.md, PROMPT.md are real files on purpose. The tools draft; Omkar decides, reviews and ships. Each repo's decision docs record what was chosen and why, so the division of labor is auditable rather than implied — and the curation and the counts on this page are computed from the files, not typed by hand.
main · 1325 files · 63 markdown docs · repo ↗
design-system/ ×8docs/ ×43
main · 408 files · 57 markdown docs · repo ↗
design-system/ ×23docs/ ×21ui-ux/ ×5
main · 410 files · 12 markdown docs · repo ↗
react-native/ ×5shop/ ×2
main · 80 files · 12 markdown docs · repo ↗
content/ ×11
03 / The sites
11 sites and apps · 9 live, 2 building · the project stacks carried from src/data/site.ts, this site's from /colophon
Portfolio · the site you’re on · continuous · live
The site you’re on. Every page renders whole from data files at build time — the collections in 04 below carry them — and every change ships through a logged version in the CHANGELOG.
the receipt · /colophonsource repo ↗the dated present · /now
Product · Retail management & e-commerce · 2025–26 · live
One retail business, two applications: a Next.js ERP for the owner — POS with barcode scanning and GST receipts, inventory with restock, stock-take and expiry tracking, purchases, income and expenses, udhar (credit) ledgers, analytics and reports — plus a customer storefront with its own database, cookie cart and COD/UPI checkout. Products sync from the ERP to the shop.
Open management app ↗Open customer storefront ↗GitHub (ERP) ↗
Open management app — Locked down under authentication — the store runs on it in real time.
Product · Café operations · 2026 · live
A café operating system covering the full counter: ordering with GST checkout, a live kitchen queue, bill collection, end-of-day close-out, inventory with recipes, guest loyalty and floor management. Role-based access for superadmin, owner and staff, plus QR table-side ordering and live order tracking for guests. Installable PWA on Supabase.
Client project · E-commerce · 2026 · live
Shipped to client: a storefront for a Surat-based surveillance and networking hardware business — categorized product catalog, exclusive CCTV kit bundles, Razorpay checkout with COD, GST invoicing with serial-tracked warranty, OTP customer accounts with order history and one-tap reorders, WhatsApp ordering and order tracking. Demo is live.
Product · Publishing platform · 2025–26 · live
A multi-niche technology publication with a split publishing model: one admin account with a Gemini-powered drafting tool, and open signup for writers who publish manually. Articles across 9 niches, a personal reading library, public author profiles with follows and comments, and a shopping layer with product comparisons and buying guides.
Product · Web + Android · 2026 · live
A privacy-first digital business card app that generates offline vCard QR codes — no accounts, no servers, no tracking; everything stays on device. Card studio with 36 style presets, live scan-contrast scoring and multi-format export, shipped as a web app and an Android app. Public beta v1, actively maintained.
App · Android · 2026 · live
A lightweight Android network monitor: a persistent live-speed notification with separate download and upload rates, daily Wi-Fi/mobile usage totals, calendar-backed history and per-app traffic breakdowns — plus usage-threshold alerts, signal strength in dBm and a quick Cloudflare speed test.
App · Next.js · 2024–26 · live
A weather-reactive PWA in a macOS-style Liquid Glass shell: live conditions, a 48-hour outlook, 7-day forecast and air quality over a full-viewport sky that follows the weather and time of day. Weather data is keyless from Open-Meteo behind server route handlers; an AI layer (briefing, chat, advisor, alert digest) degrades gracefully to rule-based text.
App · Google Gemini · 2024–26 · live
Generates recipes from ingredient tags and dietary preferences, powered by Google Gemini (2.5 Flash) through a Next.js API route — migrated from OpenAI and verified in the deployed codebase.
Product · In development · 2026 · building
A food ordering platform in active development. Planned scope covers menu browsing, order placement and delivery tracking; implemented features and a live link land here as they ship.
App · In development · 2026 · building
A mobile chat app with authentication and real-time messaging across devices. In active development — verified functionality and a link land here as features ship.
04 / Collections
the data files the portfolio itself renders from — stats computed at build time
src/data/site.ts
The single source of truth — projects, capabilities, experience, socials. Edit there, not in the pages.
src/data/uiuxProjects.ts
The /uiux case studies as typed content blocks; the index and three study pages render from it.
src/data/askomkar/hand.ts
AskOmkar's hand-written answer bank — retrieval, not generation.
src/data/askomkar/vectors.json
The bank, offline-embedded with MiniLM at 384 dimensions; the runtime embeds only your question.
src/app/globals.css
The token system (:root, html.dark) and the dev site’s rules.
src/app/cursor.css
The pointer’s look and the cursor: none contract.
src/lib/askomkar/matcher.ts
The cosine matcher that picks an answer locally, in your browser.
Set whole from the repo at build time · 27 versions and counting · the GitHub index generated November 9, 2026 · the builds scanned November 13, 2026.