{"_id":"@alanbuendia/folio","name":"@alanbuendia/folio","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alanbuendia/folio","version":"1.0.0","description":"Folio — a light-first React design system for office software: dense tables, calm forms and dependable overlays.","type":"module","license":"MIT","keywords":["react","design-system","component-library","ui","light-first","ibm-plex","admin","dashboard"],"main":"./dist/index.cjs","module":"./dist/index.js","types":"./types/index.d.ts","exports":{".":{"types":"./types/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./styles.css":"./dist/folio.css"},"sideEffects":["**/*.css"],"scripts":{"build":"vite build --config vite.lib.config.js","prepublishOnly":"npm run build"},"peerDependencies":{"react":">=18","react-dom":">=18"},"devDependencies":{"@vitejs/plugin-react":"^4.3.4","vite":"^5.4.11"},"publishConfig":{"access":"public"},"_id":"@alanbuendia/folio@1.0.0","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-VFvkqFr5Rsl14Z96AUtOteyyKY1h+Kr8ONkASoaTP9fmdUSFsvUJR2/5GXcwLwBH0JGh66Ai7MAKQCgl1VDeng==","shasum":"f3641cd9a165757ac3d72b776d5d280d9334177d","tarball":"https://registry.npmjs.org/@alanbuendia/folio/-/folio-1.0.0.tgz","fileCount":7,"unpackedSize":166591,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFRy50VjAAVQghczqysSPM7RJ0YtcN5XDMsBnoeZJtpaAiEA0sIngdkrn850LAtKTLP9IF6Pqxi2mF/Kp/bc/fOhdIA="}]},"_npmUser":{"name":"alanbuendia","email":"alan.buendia.dev@gmail.com"},"directories":{},"maintainers":[{"name":"alanbuendia","email":"alan.buendia.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/folio_1.0.0_1782296842139_0.042621693037647734"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-24T10:27:22.029Z","1.0.0":"2026-06-24T10:27:22.274Z","modified":"2026-06-24T10:27:22.501Z"},"maintainers":[{"name":"alanbuendia","email":"alan.buendia.dev@gmail.com"}],"description":"Folio — a light-first React design system for office software: dense tables, calm forms and dependable overlays.","keywords":["react","design-system","component-library","ui","light-first","ibm-plex","admin","dashboard"],"license":"MIT","readme":"# Folio Design System\n\n**Folio** is a React component library for *oficinista* (office-worker) interfaces — dense, professional internal tools: dashboards, admin panels, account managers, settings. The aesthetic is **light-first and sober**: real white surfaces, restrained type, and an ink-blue accent used by the eyedropper. Depth comes from three grays and 1px lines, **never** from boxes or hard shadows. There is **no dark mode**.\n\n> Think: corporate software you trust with the numbers. Calm, dense, legible, unfussy.\n\n## Install\n\n```bash\nnpm i @alanbuendia/folio\n```\n\n`react` and `react-dom` (>=18) are peer dependencies — bring your own. Import the\nstylesheet **once** at your app root (it carries the design tokens + component styles):\n\n```jsx\nimport '@alanbuendia/folio/styles.css';\nimport { Button, Table, ToastProvider, useToast } from '@alanbuendia/folio';\n\nexport default function App() {\n  return (\n    <ToastProvider>\n      <Button variant=\"primary\">New account</Button>\n    </ToastProvider>\n  );\n}\n```\n\n## Sources\n\nThis system was authored from a written brand brief (no external codebase or Figma was attached). The typeface is **IBM Plex** — the genuine brand font, free via Google Fonts; `@font-face` rules point at Google's static woff2 hosting (`tokens/fonts.css`). If you have licensed/self-hosted IBM Plex binaries, drop them in `assets/` and update those `src:` URLs.\n\n---\n\n## Content fundamentals\n\nHow Folio writes copy:\n\n- **Voice:** plain, precise, operational. It names things accurately and stops. No marketing gloss, no exclamation, no hype.\n- **Person:** address the user as **you** (\"Sign out inactive sessions automatically\"); the product refers to itself as **Folio**, rarely \"we\".\n- **Casing:** **Sentence case** everywhere — buttons, headings, menu items (\"New account\", not \"New Account\"). The *only* uppercase is the mono **overline/eyebrow** label (`.folio-overline`), used for section kickers and KPI labels.\n- **Numbers & data:** always IBM Plex **Mono** with tabular figures — money, counts, IDs (`ACC-04821`), dates (`2026-06-21`), deltas (`+12.4%`). Money is explicit: `$48,690`.\n- **Labels:** terse nouns (\"Owner\", \"Region\", \"MRR\", \"Renews\"). Helper text is one calm sentence (\"As it appears on invoices and filings.\").\n- **Status:** a small vocabulary — Active / Pending / Overdue / Draft / Enterprise. Lower-stakes than it sounds; stated, not shouted.\n- **Emoji:** none. Ever. Icons carry meaning instead.\n- **Tone example —** a destructive warning: *\"This permanently removes all accounts, invoices, and members. This cannot be undone.\"* Direct, no drama.\n\n---\n\n## Visual foundations\n\n**Color.** White (`#FFFFFF`) is the canvas — used generously, never tinted. Text and structure are the three grays: `#18181B` (primary), `#52525B` (secondary), `#A1A1AA` (muted/icons). The single structural line is `#EAEAEA` at 1px. The accent is **ink blue `#2D4A7C`**, used *con cuentagotas* — one or two touches per view: the primary button, the active nav item, a focus ring, a selected row tint (`#EEF2F8`). Semantic colors are deliberately **muted and desaturated** so they sit inside the sober palette rather than fighting it: success `#2F6F4F`, warning `#8A6D1F`, danger `#9A3D38` — each paired with a faint tint for fills.\n\n**Type.** IBM Plex, three roles, strictly separated:\n- **Serif** (display) — page and section titles only. Weight 500. Gives the system its quiet editorial authority.\n- **Sans** (UI/body) — everything interactive and prose. Base 14px; 13px in dense rows.\n- **Mono** (data/labels) — figures, IDs, dates, and the uppercase overline. Tabular numerals.\n\n**Spacing.** 4px grid. Dense by default — generous enough to breathe, tight enough to show a lot at once. Page gutters 24px; card padding 20px; table cells 11px vertical (8px when `dense`).\n\n**Backgrounds.** Flat white. **No** gradients, images, textures, or patterns anywhere in the UI chrome. The folded-page logo mark is the only illustrative element.\n\n**Depth.** The 1px line is the primary hierarchy device — borders group, dividers separate. Shadows are reserved exclusively for true overlays (menus, dialogs, toasts) that float above the page: soft, low, `--shadow-popover` (very diffuse, very low opacity — never a hard shadow). Cards are flat: 1px border + 6px radius, no shadow.\n\n**Borders & radii.** 1px solid `#EAEAEA` (or `#D4D4D8` for input borders / hover). One subtle radius does most of the work — **6px** for inputs, buttons, cards, and menus; **10px** for dialogs; **pill** (`999px`) reserved for badges, avatars, status dots, and the switch.\n\n**Corners & cards.** A Folio card = white fill, 1px `--line` border, 6px radius, optional header/footer divided by 1px rules; the footer sits on a `--gray-50` sunken bar. Never a colored left-border accent, never a drop shadow.\n\n**Animation.** Sober and functional — one expo curve (`cubic-bezier(0.16,1,0.3,1)`) settles everything; **no bounces, no springs, no decorative loops**. Motion is centralised in `folio/motion/tokens.css` (`--ease-out`, `--dur-1..4`) and every animation is transform/opacity-based (so content is never hidden when paused) and gated behind `prefers-reduced-motion`. The refined micro-interactions are: a sliding tab underline, an animated-height accordion, a fade+scale tooltip/menu/popover, a shimmer skeleton, an indeterminate progress bar, count-up stats, and grow-in chart bars. Reusable helpers ship with the library: `useReducedMotion`, `useInView`, `usePresence`, `CountUp`, plus `Portal` / `Popover` / `useAnchoredPosition` for anchored overlays.\n\n**Overlays.** Anything floating (Dialog, Drawer, Menu, Combobox, Tooltip, Command Palette, Toaster) renders through a **portal to `<body>`** so it escapes any transformed/clipping ancestor, and closes on Escape / outside-click. The Toaster (`ToastProvider` + `useToast`) adds stacking, slide-in/out and auto-dismiss.\n\n**Hover states.** Subtle: secondary/ghost controls fill to `--gray-50`; table rows fill to `--gray-50`; the primary button darkens to `--ink-hover`. Never scale or lift.\n\n**Press / active.** Color shift only (darker ink, tint fill) — no shrink, no shadow. Active nav and selected rows use the `--ink-tint` wash with ink text.\n\n**Focus.** 2px ink outline (`:focus-visible`) or a soft 3px ink ring on text fields (`--focus-shadow`). Always visible, always ink.\n\n**Transparency & blur.** Not used. Surfaces are opaque. (The only translucency is inside shadow rgba.)\n\n**Imagery.** None by default. Avatars are mono initials on a neutral fill with a hairline border (square for organisations, circle for people).\n\n---\n\n## Iconography\n\n- **Set:** a curated subset of **[Lucide](https://lucide.dev)** (MIT) — the line family that matches Folio's 1px structural aesthetic. Stroke-based, 2px stroke, `currentColor`, 16px default (14px in dense tables).\n- **Delivery:** shipped as the `Icon` component (`components/core/Icon.jsx`) with inline path data — no icon font, no external request, no SVG files to manage. Reference by name: `<Icon name=\"search\" />`.\n- **Substitution note:** the brief specified no icon set, so Lucide was chosen as the closest fit to the line aesthetic. If you'd prefer a different family (e.g. Phosphor, Heroicons), swap the path dictionary in `Icon.jsx` — the API stays the same.\n- **Emoji / unicode:** never used as icons.\n- **Logo:** the folded-folio mark (`assets/folio-mark.svg`) and horizontal lockup (`assets/folio-wordmark.svg`) are drawn in 1px ink line to match everything else.\n\n---\n\n## Prototype\n\n`prototype/index.html` is a functional, navigable product built entirely from the system's own components — the reference for how Folio feels in motion. A left sidebar switches between four screens, each with real interactivity:\n\n- **Components** — a showcase of palette, type specimen, buttons, inputs, badges, and a calm \"Density\" table, each annotated with a mono *ficha* spec label (variant, radius, focus…) like an archive tab.\n- **Dashboard** — serif metric tiles over a dense accounts table, with an overdue-invoices banner.\n- **Accounts** — full table with a search box that filters rows live and status dots.\n- **Settings** — an editable form with a working switch and live validation (helper text turns red when a required field is emptied).\n\nA **New account** dialog opens with a subtle fade+scale; screen changes use a short transform slide; rows and buttons have real hover/active/focus states. All motion is transform-based and gated behind `prefers-reduced-motion`, and the layout is responsive (the sidebar collapses to a drawer under 860px).\n\n---\n\n## Index / manifest\n\nRoot:\n- `styles.css` — the single entry point consumers link (`@import` list only).\n- `tokens/` — `fonts.css`, `colors.css`, `typography.css`, `spacing.css`, `base.css`.\n- `assets/` — `folio-mark.svg`, `folio-wordmark.svg`.\n- `guidelines/` — foundation specimen cards (Type, Colors, Spacing, Brand).\n- `readme.md` (this file), `SKILL.md`.\n\nComponents:\n- **core/** — `Icon`, `Button` (+ `loading`), `IconButton`, `Badge`, `Tag`, `Card`, `Avatar`, `Divider`, `Kbd`, `Spinner`\n- **forms/** — `Input`, `Textarea`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Switch`, `Field`\n- **navigation/** — `Tabs`, `Breadcrumb`, `SidebarNav`, `Accordion`, `Pagination`, `Menu`, `CommandPalette`\n- **data/** — `Table`, `StatTile`\n- **feedback/** — `Banner`, `Tooltip`, `Dialog`, `Drawer`, `Progress`, `Skeleton`, `Toast`, `ToastProvider`/`useToast`\n- **overlays/** — `Popover`, `Portal`, `useAnchoredPosition`\n- **backgrounds/** — `Aurora`, `Spotlight`, `DotField`, `GridLines`\n- **motion/** — `useReducedMotion`, `useInView`, `usePresence`, `CountUp`/`useCountUp`\n\nUI kits:\n- **ui_kits/folio-console/** — the Folio Console: an interactive shell (sidebar + topbar) with **Dashboard**, **Accounts** (dense, sortable, filterable table), and **Settings** screens. `index.html` is the click-through entry.\n\nPrototype:\n- **prototype/** — the functional product prototype (see the *Prototype* section above). Screens are `ProtoDashboardScreen` / `ProtoAccountsScreen` / `ProtoSettingsScreen` / `ComponentsScreen`, wired by `Shell.jsx` in `index.html`. Named with a `Proto` prefix so they don't collide with the UI-kit screens in the bundle namespace.\n\nEach component directory has a `.d.ts` (props contract), `.prompt.md` (usage), and a `@dsCard` HTML specimen. The `_ds_bundle.js`, `_ds_manifest.json`, and `_adherence.oxlintrc.json` files are generated by the compiler — do not edit them.\n","readmeFilename":"readme.md","_rev":"1-0c7908358b3169104bf4d16a08c4f3e9"}