README review from a newcomer to css-blocks

Open
#237 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
52/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
css
Domain
documentation

Research direction

Review the referenced sections of README.md, especially the block/scope examples and the terminology around states, resolutions, and global states. Compare the surrounding explanations so the new examples show concrete usage and output, then correct the listed grammar, spelling, and wording issues. Done means a newcomer can distinguish block, scope, class, state, and sub-state selectors from the README alone.

Written by the indexing model from the issue text.

Description

After reading the entire README, I still don't understand when I should be using block or the scope pseudo selector.

In this example, it was first mentioned that ":scope selector is automagically applied to the template's root-level element." It will be helpful to have the file name, output HTML file and CSS file to see exactly how :scope selector is applied. The code snippet example in its current state doesn't provide any clarification.

I think that it will be helpful to have an example in the beginning that can demonstrate what block, scope, class, state, sub-state selectors are. Maybe a tweet? The code snippets from line 128 - 195 are all abstract at the moment, e.g.

:scope { 
  block-name: custom-block-name; 
  /* 👆 optional! */
  /* ... more styles ... */
}

"To learn how to install css-blocks for in your application" -- for should be removed

"Blocks may can contain other classes " -- may should be removed

"You may not use a Block class outside of it's " -- should be its

"hasn't yet been implemented yet, " - should be "has not yet been implemented"

"The resolution logic for @blocks to node_modules " -- should be @blocks

"Sub-states of a State are mutually exclusive and an element may only be in one sub-state of that state at any given time."

Not everyone may be familiar with this terminology, it may be helpful to give a quick explanation before the code snippet. e.g.

"For example, a button can only be one color (state) at any time. It can be red, blue, or yellow (sub-state)"

Is this suppose to beClass State?

Is this suppose to beClass Sub-State?

"If you have dynamic classes or states in your template, it will ask you to provide explicit resolutions between Blocks that even only have a chance of being used together on the same element." - what are you trying to say here? Suggest to change the wording, and provide an example of this problem and how it will be resolved.

"In rare occasions, a Block may choose to declare declare that a certain State is global. " -- delete a "declare"

Dominant language
TypeScript
Stars
6.3k
Forks
154
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from linkedin/css-blocks

All issues in linkedin/css-blocks

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.