Example apps & documentation (usage, contribution)

.changeset/healthy-jeans-flash.md

@@ -0,0 +1,5 @@
+---
+"@animareflection/ui": minor
+---
+
+Add `Text` component

.changeset/heavy-vans-travel.md

@@ -0,0 +1,5 @@
+---
+"@animareflection/ui": minor
+---
+
+Add `Button` component

.eslintignore

@@ -2,6 +2,7 @@
 build
 coverage
 generated
+examples
 storybook-static
 
 # see https://github.com/storybookjs/eslint-plugin-storybook#installation

CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Follow the [changesets documentation](docs/changesets.md) for guidelines on how to create changesets, which describe changes you've created.

README.md

@@ -1,6 +1,10 @@
 # ANIREF Design System & UI Kit
 
-Universal design system and component library for Anima Reflection.
+Universal design system and component library for Anima Reflection, powered by [Panda](https://panda-css.com/) and [Ark](https://ark-ui.com/).
+
+## Quick Start
+
+Follow the [prerequisities](docs/usage.md#prerequisites) to install Panda in your project, then follow the [package install instructions](docs/usage.md#from-published-package).
 
 ## Local Development
 
@@ -11,6 +15,8 @@ Universal design system and component library for Anima Reflection.
      - [tsup](https://tsup.egoist.dev/) in watch mode
      - [Storybook](https://storybook.js.org/) in development mode (default port: `6006`, e.g. http://localhost:6006)
 
+If you'd like to develop outside of Storybook, as in a dedicated app, follow the [prerequisities](docs/usage.md#prerequisites), then follow the [local usage instructions](docs/usage.md#local).
+
 ## License
 
 The code in this repository is licensed under MIT, &copy; Anima Reflection LLC. See <a href="LICENSE.md">LICENSE.md</a> for more information.

docs/changesets.md

@@ -0,0 +1,27 @@
+# Changesets 🦋
+
+Changesets ([Wikipedia](https://en.wikipedia.org/wiki/changeset)) represent an _intent_ to evolve a project in the form of a collection of changes. This project uses a tool with the same name, [Changesets](https://github.com/changesets/changesets), to manage them and handle the versioning, changelog generation, and release lifecycle.
+
+## Creation
+
+1. To create a changeset, run `yarn changeset` in the project directory.
+
+2. You will be prompted to select a bump type, based on the [SemVer](https://semver.org/) spec.
+
+3. Write a message describing the change, using present tense and starting with a verb. For example, if you are adding a new component called `Card`, you might write:
+
+```
+Add `Card` component
+```
+
+If you're fixing a bug for the Card component, you might write:
+
+```
+Fix `Card` resizing after initial page load
+```
+
+After the changeset is created, it will be added to the `.changeset` folder, where it can be safely modified and committed. There is no limit to the number of changesets you can create, even in one PR.
+
+## Learn More
+
+View the [official Changesets documentation](https://github.com/changesets/changesets/tree/main#documentation) to learn more about the tool and how to use it.

docs/usage.md

@@ -0,0 +1,70 @@
+# ANIREF UI Library Usage
+
+Follow these steps to use the ANIREF UI library in your project.
+
+## Prerequisites
+
+1. Install [Panda 🐼](https://panda-css.com/): `yarn add -D @pandacss/dev`
+
+2. Create a Panda config file similar to this (Panda looks for `panda.config.ts` by default):
+
+```ts
+// panda.config.ts
+import { anirefPreset } from "@animareflection/ui";
+import { defineConfig } from "@pandacss/dev";
+
+const pandaConfig = defineConfig({
+  preflight: true,
+  presets: ["@pandacss/dev/presets", anirefPreset],
+  include: ["src/**/*.{ts,tsx}"],
+  outdir: "src/generated/panda",
+});
+
+export default pandaConfig;
+```
+
+3. Create a CSS file and import it into your project. You can name the CSS file anything you want, just make sure you import it early in your project. For example:
+
+```css
+/* main.css */
+@layer reset, base, tokens, recipes, utilities;
+@import url("@animareflection/ui/index.css");
+```
+
+```tsx
+// App.tsx
+import "main.css";
+
+const App = () => <></>;
+```
+
+Now you are ready to install the UI library. You can either install it [from the published package](#from-published-package) or from a [local clone](#local) on your local filesystem. The latter is useful if you are developing the library.
+
+## Remote
+
+Install from remote repository: `yarn add @animareflection/ui`
+
+## Local
+
+This workflow is ideal for local development.
+
+1. Install [yalc](https://github.com/wclr/yalc)
+2. **Within the root UI library directory**, build the UI library: `yarn build` (or `yarn dev` for continuous builds)
+3. **Within the project directory:**
+
+   1. Install dependencies: `yarn`
+   2. Link the UI library: `yalc link @animareflection/ui`. Linking will not modify `package.json`, it will just symlink the package into your `node_modules`. Note that the package must be published to the `yalc` store first (this happens automatically after a successful build of the UI library)
+
+      > 💡 **Note:** if you receive a `Cannot find module '@animareflection/ui' [...]` error and `yarn && yalc link @animareflection/ui` does not resolve the issue, try removing the `yalc.lock` file and then relink:
+      >
+      > ```sh
+      >  rm yalc.lock && yalc link @animareflection/ui
+      > ```
+
+      > 💡 **Note:** every time you install or modify dependencies (e.g. run `yarn` or `yarn add [...]`), the package symlink will be cleared, and will need to be relinked:
+      >
+      > ```sh
+      >  yarn && yalc link @animareflection/ui
+      > ```
+
+      > 💡 **Note:** if the UI library build fails, this will cause trickling errors. Make sure the UI library builds successfully if you are still having issues.

examples/README.md

@@ -0,0 +1,21 @@
+# ANIREF UI Example Apps
+
+## Overview
+
+- `next`: Next.js example
+- `vite`: React + Vite example
+
+## Run
+
+### From this repository
+
+To run any of these examples from within the repository, follow the [local usage instructions](../docs/usage.md#local).
+
+### Externally (by copying the examples out of this repository)
+
+1. Simply install the included dependencies and add the UI library package:
+
+```sh
+yarn
+yarn add @animareflection/ui # (or link with `yalc` as above)
+```

examples/next/.eslintrc

@@ -0,0 +1,4 @@
+{
+  "root": true,
+  "extends": "next/core-web-vitals"
+}

examples/next/.gitignore

@@ -0,0 +1,5 @@
+.yarn
+.yalc
+yalc.lock
+.next
+next-env.d.ts

examples/next/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: pnpm

examples/next/next.config.js

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+module.exports = nextConfig;

examples/next/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "ui-next-example",
+  "private": true,
+  "license": "MIT",
+  "scripts": {
+    "dev": "rm -rf .next && next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "devDependencies": {
+    "@pandacss/dev": "^0.9.0",
+    "@types/node": "^20.4.6",
+    "@types/react": "^18.2.18",
+    "@types/react-dom": "^18.2.7",
+    "eslint": "^8.46.0",
+    "eslint-config-next": "^13.4.12",
+    "typescript": "^5.1.6"
+  },
+  "dependencies": {
+    "next": "^13.4.12",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

examples/next/panda.config.ts

@@ -0,0 +1,16 @@
+import { anirefPreset } from "@animareflection/ui";
+import { defineConfig } from "@pandacss/dev";
+
+/**
+ * Panda configuration.
+ *
+ * @see https://panda-css.com/docs/references/config
+ */
+const pandaConfig = defineConfig({
+  preflight: true,
+  presets: ["@pandacss/dev/presets", anirefPreset],
+  include: ["src/**/*.{ts,tsx}"],
+  outdir: "src/generated/panda",
+});
+
+export default pandaConfig;

examples/next/src/app/layout.tsx

@@ -0,0 +1,18 @@
+import { ReactNode } from "react";
+
+interface Props {
+  children: ReactNode;
+}
+
+/**
+ * Root application layout.
+ */
+const RootLayout = ({ children }: Props) => (
+  <html lang="en" style={{ height: "100%" }}>
+    <head />
+
+    <body>{children}</body>
+  </html>
+);
+
+export default RootLayout;

examples/next/src/app/page.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { Circle, Flex, Grid, Square, Text } from "@animareflection/ui";
+
+import "main.css";
+
+const HomePage = () => (
+  <Flex
+    gradientFrom="white"
+    gradientTo="brand.primary.100"
+    bgGradient="to-b"
+    direction="column"
+    h="100%"
+    align="center"
+    gap={4}
+    pt={12}
+  >
+    <Text color="brand.primary.500" fontSize="3xl" fontWeight="bold">
+      Anima Reflection UI library demo
+    </Text>
+
+    <a href="https://nextjs.org/" target="_blank" rel="noopener noreferrer">
+      <img
+        src="https://upload.wikimedia.org/wikipedia/commons/8/8e/Nextjs-logo.svg"
+        width="200px"
+      />
+    </a>
+
+    <Grid
+      gridTemplateColumns="1fr 1fr"
+      px={4}
+      w="100%"
+      alignItems="center"
+      justifyItems="center"
+    >
+      <Square
+        size={40}
+        color="white"
+        bgColor="brand.primary.500"
+        fontWeight="bold"
+        fontSize="2xl"
+      >
+        Square
+      </Square>
+
+      <Circle
+        size={40}
+        bgColor="brand.secondary.300"
+        fontWeight="bold"
+        fontSize="2xl"
+      >
+        Circle
+      </Circle>
+    </Grid>
+  </Flex>
+);
+
+export default HomePage;

examples/next/src/main.css

@@ -0,0 +1,2 @@
+@layer reset, base, tokens, recipes, utilities;
+@import url("@animareflection/ui/index.css");

examples/next/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "baseUrl": "src",
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}