Better readme, move kit-of-parts => jambonz-ui

README.md

@@ -5,33 +5,36 @@ jambonz
 
 ![](/public/jambonz.png)
 
-## Jamstack
+## Deploy targets
 
-- [jambonz.vercel.com](https://jambonz.vercel.app)
+This app can easily be deployed to multiple targets including Vercel, Netlify or AWS+circleci.
 
-## AWS / CircleCI
+- Vercel
+  - [jambonz.vercel.com](https://jambonz.vercel.app)
+- AWS+circleci
+  - Could easily be implemented as in this repo [here](https://github.com/kitajchuk/punxy#aws--circleci).
 
-- TBD :)
+## Dev start
 
-## Dev
+Clone this repository and install [yarn](https://yarnpkg.com/getting-started/install). From app root:
 
-### Install
 - `yarn install`
-
-### Work
+  - Installs node packages
 - `yarn dev`
-- Served at [localhost:3000](http://localhost:3000)
+  - Serves local dev at [localhost:3000](http://localhost:3000)
 
-### UI library
-- [Kit of Parts](http://localhost:3000/kit-of-parts)
+Other packages being used prominently in this apps source code are [classnames](https://www.npmjs.com/package/classnames) and [nanoid](https://www.npmjs.com/package/nanoid#react).
 
-### Static
-- Static data with [yamljs](https://www.npmjs.com/package/yamljs)
-- Static props with [Next.js getStaticProps](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation)
-- Data files in `/data/`
-- JS data util in `/lib/data.js`
+## Jambonz UI library
 
-### Docs
-- Using [Nextra](https://nextra.vercel.app)
-- [Source repository](https://github.com/shuding/nextra/)
-- Source files in `/pages/docs/`
+This app is being composed in the manor of `module > component > element`, wherein a page is a module which is made up of components that are comprised of elements. We are using [Next.js](https://nextjs.org) [SASS](https://nextjs.org/learn/basics/assets-metadata-css/css-styling) located in the `styles` directory and loaded globally in [pages/_app.js](/pages/_app.js). A generally simple BEM CSS module naming convention is being used prominently. JS components are in the `components` directory. The `jambonz-ui` component consists of reusable design element components.
+
+You can view examples of the Jambonz UI component elements on this page [here](https://jambonz.vercel.app/jambonz-ui).
+
+## Static page data
+
+We are using static data with [yamljs](https://www.npmjs.com/package/yamljs) and [Next.js static props](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation). Data files are located in the `data` directory. There's a JS data utility in `lib/data.js` that provides a method for "fetching" the static data for use with a Next.js pages async `getStaticProps` SSR method.
+
+## Jambonz developer docs
+
+The project is using [Nextra.js](https://nextra.vercel.app) which provides a stylized developer docs theme for Next.js. We are currently loading theme CSS styles with the `styles/_nextra.scss` partial. Currently it is being used to hide the frontend page links from the Nextra sidebar nav as there is no current way to do this using pure nextra config. There is a [Github issue here](https://github.com/shuding/nextra/issues/59) referring to "Page exclusion from docs".