@code-sherpas/pharos-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Code Sherpas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @code-sherpas/pharos-react
+
+React component library for Code Sherpas. Consumes
+[`@code-sherpas/pharos-tokens`](https://github.com/code-sherpas/pharos-tokens)
+as a peer dependency. Built with Vite library mode, React 19, Tailwind v4.
+
+## What's in this package
+
+This package provides the **React component layer** of Code Sherpas's design
+system. It does not define design values — those live in `pharos-tokens`.
+
+## Installation
+
+```bash
+pnpm add @code-sherpas/pharos-react @code-sherpas/pharos-tokens
+# or npm / yarn
+```
+
+`@code-sherpas/pharos-tokens` is a peer dependency and must be installed
+explicitly alongside this package.
+
+## Usage
+
+```ts
+// Root entry file (e.g. main.tsx, app/layout.tsx)
+import '@code-sherpas/pharos-react/styles.css';
+```
+
+```tsx
+import { PharosHello } from '@code-sherpas/pharos-react';
+
+export function Demo() {
+  return <PharosHello name="Alexandria" />;
+}
+```
+
+## Rules for consumers
+
+See [RULES.md](./RULES.md) — published with the package.
+
+## Storybook
+
+The live component reference runs on Storybook 10 + `@storybook/react-vite`.
+
+- `pnpm storybook` — dev server on port 6006.
+- `pnpm build-storybook` — static build to `storybook-static/`. The hosted
+  URL will be published once Render deployment is wired up (phase 1B.4 /
+  1B.5).
+
+## Contributing
+
+1. `pnpm install`
+2. Implement the component under `src/components/<Name>.tsx`, export it from
+   `src/index.ts`.
+3. Add a story alongside: `src/components/<Name>.stories.tsx`.
+4. Add tests under `tests/` (Vitest + Testing Library).
+5. `pnpm build` — verify the Vite library bundle compiles cleanly.
+6. `pnpm build-storybook` — verify stories render.
+7. `pnpm test` / `pnpm typecheck` / `pnpm lint` / `pnpm format:check`.
+8. `pnpm changeset` — declare the type of change (patch / minor / major).
+9. Open a PR.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/RULES.md

@@ -0,0 +1,90 @@
+# Rules for consumers of `@code-sherpas/pharos-react`
+
+This file ships with the package (`files` includes `RULES.md`). Every
+consumer — `alexandria-web-application`, `alexandria-design`, and any future
+app — must follow these rules.
+
+## 1. Only Pharos components for UI
+
+Forbidden:
+
+- Hand-rolled `<button>` / `<input>` when `Button` / `Input` exists in
+  `@code-sherpas/pharos-react`.
+- Importing primitives (`@radix-ui/*`, `@base-ui-components/*`, `antd`,
+  `@heroicons/*`, `@headlessui/*`) directly. Pharos wraps what it needs.
+- Copy-pasting a Pharos component into the consumer and modifying it. If
+  Pharos is missing a variant, open an issue in this repo.
+
+## 2. Use the canonical names
+
+Pharos names follow shadcn/ui > Base UI > ARIA APG (tiebreaker: shorter
+name). If you are migrating Alexandria, translate the old name to the Pharos
+canonical one — do not alias.
+
+| Alexandria-ish             | Pharos canonical         |
+| -------------------------- | ------------------------ |
+| `PrimaryButton` / `CtaBtn` | `<Button variant="…" />` |
+| `Modal` / `Popup`          | `Dialog`                 |
+| `Drawer` / `SidePanel`     | `Sheet`                  |
+| `Toast` / `Notification`   | `Toast`                  |
+| `Chip` / `Pill` / `Tag`    | `Badge`                  |
+
+(Full list lives in `NAMING-decisions.md` once Phase 2 starts.)
+
+## 3. Import the stylesheet once
+
+```ts
+// in your app's root entry file
+import '@code-sherpas/pharos-react/styles.css';
+```
+
+This loads the compiled Tailwind v4 output plus the `@theme inline` mapping
+to `--pharos-*`. Without it, components render unstyled.
+
+## 4. `pharos-tokens` is a peer dependency
+
+Consumers must install it explicitly. It is not transitively bundled to
+avoid duplicate CSS var declarations:
+
+```bash
+pnpm add @code-sherpas/pharos-react @code-sherpas/pharos-tokens
+```
+
+Version compatibility is declared via `peerDependencies` in
+`pharos-react/package.json`. Upgrade both together.
+
+## 5. Respect the variants API
+
+Pharos components expose their full variant axis (size, tone, intent, etc.)
+via props. Forbidden:
+
+- Overriding internal class names to "fake" a variant that does not exist.
+- Passing `className` strings that conflict with the component's theme
+  (e.g. `className="bg-red-500"` on a `<Button>` to make it red — use
+  `intent="destructive"` or open an issue).
+
+`className` is allowed for layout tweaks (margins, widths), not visual
+identity.
+
+## 6. Respect semver
+
+- Breaking change in this repo → major bump → consumers upgrade explicitly.
+- New component or variant → minor bump → consumers may adopt freely.
+- Bugfix, visual tweak, or internal refactor → patch → consumers get it for
+  free.
+
+Every PR that affects the public API includes a changeset. If your PR does
+not, CI will fail.
+
+## 7. Icons
+
+Pharos uses **Lucide** (decision D4). When a component needs an icon you do
+not pass, Pharos renders the Lucide default. If you need a custom icon,
+open a PR to add it under `src/icons/` — do not ship icons from the
+consumer that duplicate Lucide.
+
+## 8. Extensions and forks
+
+Do not publish `@yourorg/pharos-react-extended`. If a product needs its own
+components, build them in the consumer under your own naming namespace and
+document it. If the need is general, propose it in this repo.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { }