feat: APP-2612 - Update documentation, bundle library css for standalone usage

.github/workflows/storybook-publish.yml

@@ -2,8 +2,8 @@ name: Storybook Publish
 
 on:
   push:
-    tags:
-      - "*"
+    branches:
+      - main
 
 env:
   NODE_VERSION: 18

.gitignore

@@ -7,6 +7,7 @@ coverage
 # production
 build
 build.txt
+build.css
 dist
 dist-ssr
 *.local

.storybook/preview.tsx

@@ -13,7 +13,7 @@ const preview: Preview = {
         options: {
             storySort: {
                 method: 'alphabetical',
-                order: ['Docs', ['Open Design System', 'Installation'], 'Design Tokens', 'Components'],
+                order: ['Docs', ['Documentation', 'Installation', 'Changelog'], 'Design Tokens', 'Components'],
             },
         },
         backgrounds: {

CHANGELOG.md

@@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 -   Implement `Tag` component
 
+### Changed
+
+-   Update library documentation
+-   Output `build.css` file to be able to use ODS library without TailwindCSS
+
 ## [1.0.5] - 2023-11-20
 
 ### Changed

README.md

@@ -1,7 +1,7 @@
 ![Aragon](https://res.cloudinary.com/duvrxe0m9/image/upload/v1686656588/aragon-sdk_tjosse.png)
 
 <p align="center">
-  <a href="https://aragon.org/">Aragon website</a>
+  <a href="https://aragon.org/">Aragon Website</a>
   •
   <a href="https://devs.aragon.org/">Developer Portal</a>
   •
@@ -14,43 +14,14 @@
 
 # Aragon ODS
 
-Aragon Open Design System (Aragon ODS) is an open source and human-centric design system specifically designed for the Aragon App.
-It provides a unified and easy-to-use framework for creating visually consistent and engaging interfaces that prioritize
-user experience throughout the Aragon ecosystem. Aragon ODS is currently in alpha version, with documentation updates planned for Q2.
-The developed components are expected to be available in the coming months.
+The Aragon Open Design System (ODS) is an open source and human-centric design system specifically designed for the Aragon App.
+It provides a unified and easy-to-use framework for creating visually consistent and engaging interfaces, prioritizing user experience throughout the Aragon ecosystem.
 
-## Installation
-
-Install the `@aragon/ods` library and using yarn or npm:
-
-Yarn:
-
-```shell
-yarn add @aragon/ods
-```
-
-Npm:
-
-```shell
-npm install @aragon/ods
-```
+**NOTE**: The Aragon ODS library is currenlty in pre-alpha stage; breaking changes are likely to occur.
 
 ## Usage
 
-Import the `@aragon/ods` library on your application and use the components:
-
-```typescript
-import React from 'react';
-import { Tag } from '@aragon/ods';
-
-export default function App() {
-    return (
-        <div>
-            <Tag colorScheme="primary">My label</Tag>
-        </div>
-    );
-}
-```
+Visit the [Installation documentation page](https://aragon.github.io/ods/?path=/docs/docs-installation) to correctly install, setup and use the library.
 
 ## Contributing
 

docs/changelog.mdx

@@ -0,0 +1,6 @@
+import Changelog from '../CHANGELOG.md?raw';
+import { Meta, Markdown } from '@storybook/blocks';
+
+<Meta title="Docs/Changelog" />
+
+<Markdown>{Changelog}</Markdown>

docs/documentation.mdx

@@ -0,0 +1,6 @@
+import ReadMe from '../README.md?raw';
+import { Meta, Markdown } from '@storybook/blocks';
+
+<Meta title="Docs/Documentation" />
+
+<Markdown>{ReadMe}</Markdown>

docs/installation.mdx

@@ -4,46 +4,65 @@ import { Meta } from '@storybook/blocks';
 
 # Installation
 
-TODO
-
-## 1. Install the library
-
-Install the `@aragon/ods` library and using yarn or npm:
+Install the `@aragon/ods` library and using Yarn or npm:
 
 Yarn:
 
 ```shell
-yarn add @aragon/ods tailwindcss tailwindcss-fluid-type
+yarn add @aragon/ods
 ```
 
 Npm:
 
 ```shell
-npm install @aragon/ods tailwindcss tailwindcss-fluid-type
+npm install @aragon/ods
 ```
 
-**NOTE:** `react` and `react-dom` are also required to correctly use the library:
+# Setup
 
-```json
-"peerDependencies": {
-    "react": ">=17",
-    "react-dom": ">=17",
-},
-```
+You can setup the Aragon ODS library in your project with [Taildwind CSS](https://tailwindcss.com) or as a standalone library:
+
+-   Follow the [Setup with TaildindCSS](#setup-with-tailwindcss) guide if you are using or planning to use `Tailwind CSS` for your project.
+-   Follow the [Standalone Setup](#standalone-setup) guide if you are using your own or another UI library.
+
+## Setup with Tailwind CSS
+
+-   (Optional) Setup `Tailwind CSS` for your project by following their [installation guide](https://tailwindcss.com/docs/installation).
+
+-   Update the `tailwind.config.js` configuration file as follows:
 
-## 2. Usage
+    ```javascript
+    module.exports = {
+        presets: [require('@aragon/ods/tailwind.config')],
+        content: ['./src/**/*.{jsx,tsx,html}', './node_modules/@aragon/ods/**/*.js'],
+    };
+    ```
 
-Import the `@aragon/ods` library on your application and use the components:
+-   Import the Aragon ODS styles in your project entry file (e.g. `src/index.js` or `App.js`):
+
+    ```typescript
+    import '@aragon/ods/index.css';
+    ```
+
+## Standalone Setup
+
+-   Import the Aragon ODS stylesheet bundle in your project entry file (e.g. `src/index.js` or `App.js`):
+
+    ```typescript
+    import '@aragon/ods/bundle.css';
+    ```
+
+# Usage
+
+Import the `@aragon/ods` library on your application and start using the components:
 
 ```typescript
 import React from 'react';
-import { Tag } from '@aragon/ods';
-
-export default function App() {
-    return (
-        <div>
-            <Tag colorScheme="primary">My label</Tag>
-        </div>
-    );
+import { Button } from '@aragon/ods';
+
+export const App: React.FC = () => (
+    <div>
+        <Button variant="primary" size="lg">My label</Tag>
+    </div>
 }
 ```

package.json

@@ -8,6 +8,7 @@
   "files": [
     "dist",
     "index.css",
+    "build.css",
     "src/**/*.css",
     "src/assets/fonts/*",
     "tailwind.config.js"
@@ -41,11 +42,13 @@
   ],
   "author": "Aragon Association",
   "dependencies": {
-    "@radix-ui/react-progress": "^1.0.3",
-    "classnames": "^2.3.2",
+    "@radix-ui/react-progress": "^1.0.0",
+    "classnames": "^2.3.0",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "tailwindcss": "^3.3.3"
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^3.3.0"
   },
   "devDependencies": {
     "@babel/core": "^7.23.3",
@@ -92,8 +95,10 @@
     "prettier-plugin-organize-imports": "^3.2.3",
     "prettier-plugin-tailwindcss": "^0.5.4",
     "rollup": "^4.5.0",
+    "rollup-plugin-postcss": "^4.0.2",
     "rollup-plugin-visualizer": "^5.9.2",
     "storybook": "^7.5.3",
+    "tailwindcss": "^3.3.5",
     "ts-jest": "^29.1.1",
     "typescript": "^5.2.2"
   },

rollup.config.js

@@ -5,6 +5,7 @@ const terser = require('@rollup/plugin-terser');
 const typescript = require('@rollup/plugin-typescript');
 const { visualizer } = require('rollup-plugin-visualizer');
 const svgr = require('@svgr/rollup');
+const postcss = require('rollup-plugin-postcss');
 
 const tsConfig = require('./tsconfig.json');
 const { outDir } = tsConfig.compilerOptions;
@@ -64,4 +65,9 @@ module.exports = [
             terser(),
         ],
     },
+    {
+        input: 'index.css',
+        output: { file: 'build.css' },
+        plugins: [postcss({ plugins: [], extract: true, minimize: true })],
+    },
 ];

src/styles/index.mdx

@@ -4,4 +4,38 @@ import { Meta } from '@storybook/blocks';
 
 # Design Tokens
 
-TODO
+The design tokens in the `@aragon/ods` UI library serve as the foundational elements for creating consistent and
+visually appealing interfaces. These tokens are implemented using [CSS custom variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) and, when integrated with
+Tailwind CSS, they can be conveniently accessed through Tailwind classes. When used as a standalone library, design
+tokens should be used as CSS custom properties.
+
+## Usage
+
+### With Tailwind CSS
+
+In projects using both `@aragon/ods` and `Tailwind CSS`, design tokens are readily available as Tailwind classes. For instance:
+
+```html
+<div class="mt-2 bg-primary-500">
+    <!-- Content with design tokens applied -->
+</div>
+```
+
+### Standalone Usage
+
+When using `@aragon/ods` as a standalone library, design tokens are applied as CSS custom properties. For example:
+
+```css
+.my-section {
+    margin-top: var(--ods-space-2);
+    color: var(--ods-color-primary-500);
+}
+```
+
+## Categories
+
+-   **Primitive**: Establish the core elements of the design system, including colors, typography, spacing, and more.
+
+-   **Semantic (SOON)**: Provide an abstraction layer over primitive tokens, enabling the definition of application themes.
+
+-   **Component-Specific (SOON)**: Allow users to customize individual components according to their preferences.

src/utils/formatterUtils/formatterUtils.mdx

@@ -27,19 +27,28 @@ export const FormatExampleTable = ({ values, formatShort, formatLong }) => (
 
 # Formatter Utils
 
-Use the `formatterUtils` utility to format numbers and dates (soon) across the application.
+Use the `formatterUtils` utility to format numbers and dates (soon) across your application.
 
-## Number formatting
+## Number Formatting
 
-The `formatNumber` utility currently supports 5 formats, which are used depending on the type of data that is being
-formatted. For each format we have then 2 variants:
+The `formatNumber` utility currently supports 5 formats, each with two variants based on the type of data being formatted:
 
--   **Long**: the full value which we show only when there is enough space and the user needs precision
--   **Short**: the abbreviated value which we show when space is limited and the user doesn't need as much precision
+-   **Long**: The full value is displayed when there is enough space and the user needs precision.
+-   **Short**: An abbreviated value is shown when space is limited and less precision is required.
+
+### Usage
+
+Import the `formatterUtils` utility and start using it as follows:
+
+```typescript
+import { NumberFormat, formatterUtils } from '@aragon/ods';
+
+const formattedQuantity = formatterUtils.formatNumber(amount, { format: NumberFormat.TOKEN_AMOUNT_SHORT });
+```
 
 ### Generic quantity
 
-Generic quantities are any countable thing, such as members, proposals, votes, block number, etc.
+Generic quantities represent anything countable, such as members, proposals, votes, block numbers, etc.
 
 **Examples**:
 
@@ -51,7 +60,7 @@ Generic quantities are any countable thing, such as members, proposals, votes, b
 
 ### FIAT totals
 
-Fiat totals are any summed monetary value, such as treasury, fiat equivalents for withdrawals, etc.
+Fiat totals represent any summed monetary value, such as treasury amounts or fiat equivalents for withdrawals.
 
 **Examples**:
 
@@ -66,7 +75,7 @@ Fiat totals are any summed monetary value, such as treasury, fiat equivalents fo
 
 ### Token amounts
 
-Token amounts are any whole or fractional amount of token, such as an amount withdrawn, balance, or voting power.
+Token amounts represent whole or fractional amounts of tokens, such as withdrawals, balances, or voting power.
 
 **Examples**:
 
@@ -81,7 +90,7 @@ Token amounts are any whole or fractional amount of token, such as an amount wit
 
 ### Token prices
 
-Token prices are the actual price of a specific token. For the token price format, the long and short variants are the same.
+Token prices represent the actual price of a specific token. For token price formatting, the long and short variants are the same.
 
 **Examples**:
 
@@ -96,8 +105,7 @@ Token prices are the actual price of a specific token. For the token price forma
 
 ### Percentages
 
-Percentages are used in various places, such as to describe voting outcomes, governance parameters, voting power out
-of the total supply, etc.
+Percentages are used in various contexts, such as describing voting outcomes, governance parameters, or voting power out of the total supply.
 
 **Examples**: